Code Comments: Why They Don't Indicate Failure

2017-06-16

_ Editor's Note: Since writing this article, it was brought to my attention by Tonya Mork that it's not so much code comments in general that are discouraged, but "inline" comments. With this distinction, I can actually concede that the use of these comments inside of functions are less necessary when the code speaks for itself. However, I would still argue that using comments shouldn't be considered an overt indication of failure in code. It was even brought up that dislexia can make reading code difficult, and that code comments can still have an accessibility purpose (as I argue below). With that being said, I've kept the version of the article below as I believe the discussion over the matter is fruitful and worth keeping._


If you've been doing frontend development for any length of time, you'll have noticed it seems that lots of people hate the idea of code comments. The the phrase most commonly used to support that aversion is from Robert C. Martin:> "Every comment represents a failure to make the code self explanatory."The idea is that your code should be self-documenting, and therefore comments would be useless "repeaters" of what the code is already saying; in effect, it is preferrable that the reader of the code be reading the same language of the computer. Basically: Code comments basically mean you suck at programming. To some people.Unfortunately, this idea — that is, the idea that every comment represents a failure to uphold these goals — is too black and white to apply to all programming in general. In fact, I would go so far as to claim that there is no case in where comments are detrimental to the ability of a person (author or reader) to understand the related code, and can only be beneficial in the long run. Before I explain why, however, let me make some general points for clarification:

  1. I am not making this opinion in the context of programming as a whole, but purely from the perspective of frontend development, in which I have more experience.
  2. I am sure Mr. Martin is a very smart man and a better programmer than myself. My disagreement is simply that, and not a smear on his intelligence.
  3. There will be cases where my opinion on the matter will not hold true, even if I think those cases will be extremely rare. With that in mind, let's continue.

    Avoiding Code Comments is Nonsense

    Traditionally, avoiding code comments may be worth your effort if you're in complete control of the code base. But propagating the idea as a best-practice can lead to unnecessary guilt in many developers. Here are 3 reasons why:

    1. Third-Party Code is the New Normal

    For example, they may have a third-party code-base to work with, and therefore didn't choose the naming convention of classes, functions, or any other piece of the program. In WordPress, this is insanely common, and even in frontend development where you rely on the community's solutions to problems with tools like NPM and module importing, code comments have enormous value. To require developers to avoid code comments is going to make the the ability to quickly onboard open-source contributors that much more difficult.

    2. Not Everyone is an Experienced Programmer

    Now, to be fair, Martin doesn't say you should never apply comments to your code; just that one should avoid code comments like the plague. But even in this scenario, the idea of treating comments as some sort of indicator of a failed execution of code is invalid. For example, one might have perfectly valid syntax, naming conventions, and self-documenting structure. But here's the problem: this is only obvious to the experienced programmer who can fluently read "computer-speak". In an open-source environment like WordPress and NPM, we pride ourselves on our code being accessible to the masses. Without a doubt, this accessibility of the code also invites newer programmers to browse through that code to learn. A newer programmer may not be fluent in computer language, but through the use of qualified and appropriate commenting, they can bridge that gap as a sort of translator, allowing them to grow in their knowledge and progressively need comments less and less as time goes on.

    3. Build Tools Remove All Comments

    Finally, even though going beyond the original reason of indicating a failure of self-documentation, frontend code is and should always be compiled down to as small an asset as possible. Whether this is minification or transpiling to another version of the code, it pays no consequence. The end result is the same: comments are non-existent in production. If there is no actual performance reason to avoid commenting, and comments can only help developers understand in more detail your code, why should we avoid them?

    A Possible Reason to Avoid Code Comments

    There is only one reason to avoid commenting code, and, as I'll argue in a minute, is not a real reason at all. This reason is that commenting code poorly can be either useless or misleading. Yet this is not a problem of code comments, but of the author of those comments. A code comment that doesn't properly define the related code's execution and purpose, or that is too short to be useful, is easily remedied. Though beyond the scope of this post, it takes practice to learn how to comment your code in a way that is helpful to either your future self, or a third-party who is using your code. One should still strive to adequately comment their code for the sake of easy adoption and understanding, but in a way that defines that code as succinctly and clearly as possible.

    Comment Your Code

    So, that's my rant on code commenting. Comment that crap out of your code — seriously. And don't feel bad about it. There are no downsides and only upsides. You should get really good at commenting your code. Do it so much that you are a pro. If you use Atom Editor, there is a nifty little plugin as well that will automatically give you a DocBlock snippet to fill in (I use it all the time). If you are not sure how to comment your code in a way that helps, read these DocBlock standards on PHP and JavaScript.