Thomas R Alexander

Manager, Developer, and professional problem solver

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.

9 thoughts on “Do’s and Don’ts of Code Comments

  • Al
    June 2, 2015 at 9:53 am

    “Comments should be useful, concise and compliment your code.”

    // Hello code – my you are looking good today!

  • Gernot
    June 2, 2015 at 12:13 pm

    Nice post!

    I think you missed: “Don’t insult other developers in your comments’ 🙂

    • teeohhem
      June 2, 2015 at 12:16 pm

      Haha indeed…especially since you can’t fire back without another commit ;). That’s right up there with the obligatory, “this code is self-explanatory” comment. I actually saw that once and damn near fell out of my chair.

  • bjoul
    June 2, 2015 at 3:09 pm

    Look at section: Do put longer comments above logic and short comments to the side

    The code is self explanatory/documenting in your example. Your comments just follow the previously stated “Comments that say exactly what the code does are not helpful.”

  • 代码注释中的5要与3不要 | 爱前端
    June 4, 2015 at 3:08 am

    […] 英文原文:Do’s and Don’ts of Code Comments 翻译作者:码农网 – 小峰 This article is automatically posted by WP-AutoPost : […]

  • 代码注释中的5要与3不要【转】 | 小样儿(ShowYounger)
    June 4, 2015 at 5:28 am

    […] 英文原文:Do’s and Don’ts of Code Comments 翻译作者:码农网 – […]

  • zombiecodekill
    June 13, 2015 at 2:40 am

    Haha this feels really meta. I’m commenting on your comment that developers should review and comment on other developers comments! I agree, there are a very big component of readable code and are not always given their full due because they are ignored by the compiler.

    I have an even simpler rule that I use:
    WHAT: unit tests
    HOW: production code
    WHY: comments

  • zombiecodekill
    June 13, 2015 at 4:07 am

    Also there is absolutely no excuse for commented out code, also known as zombie code. Other developers see it and think that it must be important for some reason they don’t understand when its just a load of junk. I have cut some files down by hundreds of lines just by getting rid of zombie code that has been left to haunt for years!

  • FreeBSD VPS
    May 11, 2016 at 12:06 pm

    This is especially true in testing code.  Test framework classes don’t tend to be instantiated separately and passed around as objects; they’re effectively just bundles of file-scope functionality coupled with a mechanism to reset state between tests.  In these cases, defining the test functions inline at their declaration sites has little negative effect and can reduce the amount of “boilerplate” in the test file.

Leave a Reply

Your email address will not be published. Required fields are marked *.

*
*
You may use these <abbr title="HyperText Markup Language">HTML</abbr> tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">


6 + 3 =