Code Style Guide - Comments

3 minute read Published:

Preferred coding style and best practices. This article covers commenting your code.

Comments

Comments are the most important part of your code contributions, they tell other developers why you wrote something. They should never explain how you did it, the code you wrote should speak for itself.

When writing comments, it can be helpful to sign your name. I love me some git blame, but this way others will know who to talk to even if version control history has been lost. I prefer to use a format like this:

// TODO:(rob loranger) find a fix for this terrible hack I wrote

// NOTE:(hello@robloranger.ca) || (robjloranger)
// something like these might be better suited for community projects
// public email or username where the repository is hosted

Another nice technique I saw recently, h/t @mrxinu, bulleted lists in code blocks. Makes for more aesthetically pleasing lists, or athletically, and improves readability.

/*
  NOTE:(rob loranger) future considerations to improve readability

  + clean up TODOs etc
  + reword error messages

*/

Keeping the line length short is really great, I enjoy reading something between 40 and 75 characters. As well when using a tool like godoc the output won’t wrap in the user’s terminal as most are set to 80 characters wide by default.

// This line maintains it's readability and keeps to the point.

// This line overstates the message and runs onto the next line, making the user jump around to follow the context.

Commit Messages

Comments for the codebase.

Your commit message should always say what change you made, not each step in that change. Instead of:

a5d4749 uint32 to hold counter
de21bb3 increment counter
404c2da return counter total

Something like the following is much more descriptive and provides a cleaner total change history in the repository.

a5d4749 tracker: adds counter for traffic

Longer commit messages, like those for changes to open source projects, are better written in an editor, git commit vs git commit -m "my commit msg", provides better control over the readability of your messages. The first line should be kept short, under 50 characters. This will serve as a subject line. Leave one empty line after the subject and then describe the chages you made and why, not how. This can include lists and multiple paragraphs if needed. Lastly drop in any issue references; closes #215 related #177.

Example

Tracker: add traffic counter

We needed a way to track the number of users on this api route, this counter
increments for each unique call over the api.

Note: in the future do some other more advanced stuff with this as there is this
issue that may start to appear using the current method. Also any other important
things can go here.

Always place an empty line between paragraphs and sometimes bullet lists too.

 - notice these paragraphs are wrapped at around 70 characters

 - this helps keep messages readable on the command line

closes #215, #218

Keep an eye out for the next post in the Style Guide Series.