Clean Code: Chapter 4 - Comments

Posted by Andy Huggins on January 23, 2016

The shortest description of this chapter is, Don't write comments. But it isn't really that simple. 

Building on some of the previous chapters, it seems Uncle Bob feels that comments are generally cruft that looks messy. The intentions are good when coders write them, but they end up becoming out of date or inaccurate or full of lies. Coders SHOULD maintain comments as they do code...but the reality is, they don't.

This is why it is extremely important to name functions properly with words that say what the function does. Doing so means your comment becomes redundant and can therefore be removed.

If you feel the need to write a comment, why not refactor your code so you don't need to?

If you do find that you need to write a comment, keep it short and simple.

A lot of things have been replaced by version control systems now, like there is no need to keep a comment log of changes, or attributing code to an author. All of this can be accomplished with version control systems.

Useless comments don't add anything...Example: /* User Address */ $userAddress. By using a descriptive name, it is already clear that the variable contains the user's address, the comment doesn't add anything. It contributes to coders ignoring comments because often they are meaningless.

One line particularly stood out to me "the only truly good comment is the comment you found a way not to write."

I wonder how Uncle Bob would feel about the posts I wrote about a 'docs' folder with markdown files. I see these as intent documents, where you explain how your code should be consumed, maybe explain your thinking in a particular part, or even just providing some notes to your future self to refresh the concepts of what was coded. I see these as a good thing, but maybe they are unnecessary.