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:(firstname.lastname@example.org) || (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.
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 changes you made and why, not how.
This can include lists and multiple paragraphs if needed. Lastly drop in any issue references;
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.