A Brief Commentary on Comments

Posted January 10, 2019

Code isn't art. It's a living, breathing roadmap, and good developers provide directions.

Good developers never have
"no comment"

If you're not a developer, it's hard to convey how important comments are. See the code in orange in the image up top? Those are comments. The end user never sees them and they don't affect functionality. But they provide invaluable information to other team members or developers who come along later to make revisions, such as what a block of code does, what vital connection it provides, what functionality resides in the next few lines, etc. Comments are so important that while every language denotes them in a different way, they all have a method for adding them to your HTML, CSS, JavaScript, etc.

Comments are to code what road signs are to driving. Even that's not completely accurate, because a road sign doesn't tell you why you should go 35, only that you should. Good comments explain the code ahead, justify its presence, and if you're lucky, help you make sense of potential errors you might encounter if you try to modify or update the existing code. And did I mention they save time?

My full-stack instructor, TAs, tutor and random people walking down the hall between classes hammered it home: good comments are as important as good code. For the past two days, I've disentangled code written by someone who never got that message. So when I saw the cheeky tweet tonight pictured here that begins, "When someone asks me why my code isn't documented ..." I didn't laugh.

No phone, no lights, no motor car ...

Comment-free code was the least of the problems I inherited on the page I had to update. It was created with Sitecore, a content management system, but because the original developer built the page with custom HTML, CSS and JavaScript, I had to understand every piece of code in order to move it around and still have the video modals (a.k.a. popups) work correctly.

I quickly realized much of code on the page wasn't actually being used. On-page styles were split up in different places. One of the many scripts on the page was commented out <!-- like this --> rendering the script inoperable. Even then, the developer should've explained why he left the script on the page.

Repeat after me: Comments aren't a luxury

Commenting out an unused script without context is like leaving a deflated basketball in the middle of the court. It had a purpose at one time; it might still be useful if you had a pump. But right now it's just taking up space, and you're gonna have to move it if you don't want to trip on it once the game starts.

The good news is despite the previous developer's bad practices, I figured out which code to save and which to toss. The modals work, the code is cleaner for the next dev who comes along, and I had a topic to blog about. But back to that tweet ... code isn't art. And developers who can't be bothered to comment their work aren't artists, they're lazy. As far as I'm concerned, they should be banished to build radios out of coconuts on Gilligan's Island to atone for their sins. Try that without directions, mate! Cause that's what it's like to trying to navigate your sloppy code. :)