3 quick hacks for better coding comments

Written by

Walter G.

Published on

March 06 2020

Modified on

March 13 2020

I have read many comments in my days. Some were very much helpful and made my workday a breeze. While others were cryptic messages from the past that haunted me for years on end. Just what does "do not remove until jan 2012" really mean? And why did we need to "add a 2 to offset here"? I might never know. And some were just witty comments from coders looking to blow off some steam during their stressful workdays.

// this might or might not work in 2 months..
// check back later...
function impossiblyComplex(){

}

I personally like comments and am in the camp of the more the merrier, as long as they remain relevant and non-complex. Some developers are on the opposite end, and find comments to be distracting and cumbersome and avoid them at all costs. Maybe they just aren't working on software that is complex enough to warrant commenting. It happens.

Truthfully you shouldn't be commenting every single line and you should probably not "not" comment ever. We're all adults here. Let's comment when it makes sense to comment folks.

After thousands of comments, here are some tips that I have found to be very useful in both my professional and in my personal work in order to keep a more maintainable codebase.

Note that I didn't invent these concepts. They came from years of development on hundreds of projects having worked with dozens of other very talented programmers.

I sign my comments

Before I write any actual comment related to the code, I normally tend to leave a signature behind that looks like the following:

// 3.6.2020 - WG => comment goes here

The signature includes the date the comment was written on, and my initials right after. If you are working on your own code/project then leaving your initials is probably not necessary, though I still tend to do so just in case at some point in the future someone else works on my projects.

In the corporate world however, usually 2-4 people can potentially end up modifying your code for various reasons. Because it isn't your code technically. It belongs to the project and to the company. Leaving a comment trail with a date and a person to contact makes collaborative work much easier and will reduce the inevitable confusion that comes with writing code.

Including the date of the comment gives an idea of how relevant that message is. I personally have comments in my code from 2014. There is a good chance that this code might be somewhat outdated.

No, let me reword that. That code is outdated. It's like reading a magazine from 1999 about computers and making current real-world choices based on that. So dates matter.

But more importantly, just reading the signature I know what I'm getting myself into before I modify any currently existing code. And in the corporate world, much of the time that's exactly what you will be doing.

Creating borderlines

Usually, code comes in groups, as in multiple lines of code. Comments however, tend to be directed towards a single line, causing the reader to try and figure out just where the comment starts and where it stops.

Take the following for example:

function doSomething(){
    let list = [1, 2, 3, 4];

    // add very important numbers
    list.push(5);
    list.push(8);

    // add less relevant numbers
    list.push(1);
    list.push(2);

    list.push(4);
}

In this particular example above, you can use the comments and the blank spaces to assume which numbers I am specifically referring to. But really, you would just be guessing based on context. And this can inevitably lead to bugs down the road and to a more stressful job.

We can do better. Take the following:

function doSomething(){
    let list = [1, 2, 3, 4];

    // add very important numbers
    // *********************************
    list.push(5);
    list.push(8);
    // *********************************

    // add less relevant numbers
    // *********************************
    list.push(1);
    list.push(2);
    // *********************************

    list.push(4);
}

I tend to use the asterisk for this process. And no, there is no coding specification standard for this as far as I am aware. Use whatever makes the most sense to you.

But now there is no question as to which lines of code I am referring to and so the odds of producing bugs is overall reduced. This is also something that I have begun to use in my CSS files to help break up and regroup different sections.

/* RIGHT-NAV START
**************************** */
.right-nav{
}


.right-nav .item{
}
/* RIGHT-NAV END
***************************** */

That isn't my favorite syntax for comments, I'll say that now. But it works. We still don't really have a solid foundation when it comes to standardizing CSS or with comments really.

Include a subject word

Some comments aren't necessarily tied to any logic or specific code that is written. These would include potential bugs, or code that isn't running and needs to be removed. In this case, I have found it useful to add a subject word as a prefix to relevant comments.

This method is a common practice among military email formats, which is where I adopted it from.

// TODO: Logic getting collapsed into a particle currently
function quantumComputation(){

}


// BUG: 3.6.2020 - wg => found it, didn't make it
function shouldWorkButDoesnt(){

}

In the military, subject lines would include keywords such as ACTION, REQUEST, INFO, and COORD. They tell the reader immediately what to expect from the message that follows and this makes it much easier to search through content as well.

If you see the word ACTION on an email subject, then there's a good chance that this email is time sensitive and should be looked at sooner than later.

A few examples of code related subject word that I use are TODO, BUG, REMOVE. But anything that is relevant to your work and your project is acceptable here.

TODO for example would imply an unfinished function or method that more than likely isn't running currently. And BUG is a bug, which would imply some immediacy.

As mentioned above, this makes searching for todo items and bugs across entire projects a relatively simple process. We're almost re-purposing comments as tagging mechanisms for our code if you will.

Make comments work for you

Comments many times tend to be static short sentences that never change and that you typically ignore or read only once. I see them differently though. Because comments are the only place in your code where you don't have to follow any type of rule. It interplays code-logic with your real-life thoughts and allows you to be honest with what is happening.

You are having a conversation with a future developer, and with a future version of yourself as well. You are leaving behind breadcrumbs, just in case you might need them later on.

So comment when appropriate and every now and then it's probably fine to leave a witty remark behind for some future person to read.

That's it for this post folks. May you start to incorporate some of these methods into your own code and come up with your own clever ways as well.

Comments

No messages posted yet

Add comment