Do’s and Don’ts of Code Comments

Comments in code are arguably more important than the code itself. Future you will thank present you if you are a good commenting citizen. I have read a ton of code in my lifetime and have come across some pretty amazing comments, but mostly awful ones. Here are some ways you can ensure you are writing good comments in your code:

Comments Do’s and Dont’s

Don’t tell the reader what they already know

Comments that say exactly what the code does are not helpful.

Do comment reasoning and history

If there is business logic in code that could be impacted on future updates or changes, leave a comment and more importantly, create a future ticket to address it 🙂

Don’t make long comments on one line

Nothing bothers a developer more than having to scroll horizontally to read comments. In fact, most developers will just ignore them because it is an inconvenience.

Do put longer comments above logic and short comments to the side

This is sort of like the statement above, but I wanted to spell it out. Short comments belong next to code if and only if it doesn’t exceed 120 characters on one line. Otherwise, put the comment directly above the statement.

Don’t add unnecessary comments for the sake of commenting

Commenting creates clutter. You may have been taught in school to add comments to everything because it will help the developer understand it better. This is wrong. Do me a favor and go de-pants whomever taught you this. Your code should be clean and concise enough in a way that it is self-explanatory. If your code needs to be explained line-by-line, you’re in dire need of a refactor.

Do spell things correctly in your comments

There isn’t any excuse to misspell words in your code comments. Your IDEs should have spell checkers. If they don’t, for the love of God, download a plugin and check yourself!

Do practice

Practice makes perfect. Try creating useful comments and asking another developer if the comment is useful to them. Over time, you’ll get a better sense of what constitutes a “good” comment.

Do review other comments

Comments are often overlooked in code reviews. Don’t be afraid to ask for more comments in code and question the ones that are there. If everyone can get in the habit of writing better comments, more butterflies will fly and less babies will die. That’s probably not true, but leave a comment if you disagree.

Summary

Comments are a very important part of the development process and you should always leave a comment/docstring per the standards of each development language (think about IDE integration and code sense), but don’t comment for the sake of commenting. Comments should be useful, concise and complement your code. Comments should not have to explain your code line-by-line, rather, they should aide in explaining business logic, reasoning, and future implications.