Skip to main content

Chapter 4 - Comments

Key Takeaways​

  • The best comment is the one you avoided
  • Code should explain itself
  • Comments are only really acceptable for legal purposes or complex code that can't be changed to be easier to read.
  • Don't comment bad code to explain it, fix it.
  • Comments tend to pollute and congest code bases and even often mislead the reader rather than help the readability of code.
  • Hard to maintain as code evolves, as what you're describing what necessarily stay the same.

Comments Do Not Make Up for Bad Code​

  • Rather than spend time commenting the code that is a mess, spend that time cleaning the mess.

Explain Yourself in Code​

  • Explained in previous chapters, we should be using good code readability practices to ensure that code reads well and explains itself.
    • I believe that SRP principle helps achieve this significantly as demonstrated in the example.

Good Comments​

  • Legal comments like authorship or copyright statements are necessary in code bases sometimes.
  • Informative comments like explaining what an abstract method returns, however it is preferable to have the function name describe this.
  • Explanation of intent comments like an author taking an interesting approach to a problem, you may not agree with the approach but at least you know what he is trying to do.
  • Clarification comments like translating the meaning of an obscure argument or return value. Although we should try to make this clear through code, we don't have much of a say if what we are using is not our code, so clarifying comments may be useful here.
    • Must ensure that our clarifying comments are in fact correct!
  • Warnings, it can be useful to warn users of potential risks of using a function or something of the sort.
  • TODO comments can be useful for notifying readers that a function is "in the works" or of a degenerative implementation that needs to be updated.
  • Amplification comments can be good to notify a reader that some code that may not seem important actually plays a large role.
  • Javadocs are very useful when writing a public API.

Bad comments​

  • Mumbling comments are when you put in a comment just because you feel like you should, no real thought has gone into it.
  • Redundant comments are when the comment doesn't provide any value, useless reading... the code already describes itself.
  • Misleading comments are inaccurate comments or comments with misinformation or lack of information that can lead to incorrect or bad assumptions about the code.
  • Mandated comments are comments that are their for the sake of having a comment, like saying "every function needs a comment", this will just clutter the code base.
  • Journal comments are to keep track of edits but with version control systems now, these are redundant and not necessary. They're just clutter.
  • Noise comments are ones that restate the obvious and provide no valuable information.

Don't Use a Comment When You Can Use a Function or a Variable​

Position Markers​

  • Grouping code together with big comments lines like:
// Actions ///////////////////////////////////
  • This is clutter and should be avoided, very rarely is this necessary.

Closing Brace Comments​

  • Refers to comments at the end of braces to show what that brace belongs to, these are redundant noise.
  • We should be trying to shorten our functions instead.

Attributions and Bylines​

  • Once again version control is very good at keeping track of who does what.
  • Making this attribution comments also redundant.

Commented-Out Code​

  • Once again version control systems make it possible to retrieve old code.
  • Therefore we mustn't be afraid of losing old code if we end up needing it again.
  • If code is commented out and not being used it should be eliminated.

HTML Comments​

  • "HTML in source code comments is an ABOMINATION"
  • If comments are to be extracted by some tool, it should be the responsibility of that tool and not the programmer.

Non-local Information​

  • Comments shouldn't give too much information.
  • If there is even a comment it should only provide local information not system or global information.

Too Much Info​

  • Don't put historical discussions or irrelevant descriptions in code, it only clutters it.

Inobvious Connection​

  • If you are going to write a comment you want it to be obvious what code the comment refers to.

Function Headers​

  • Short functions don't need headers, it should describe itself.
  • If we construct our functions properly with care, most if not all of our functions should be relatively short.

Javadocs in Non-public Code​

  • If code is not intended for public consumption, generating documentation pages is not really useful.
  • The extra formality of the javadoc comments amounts to cruft and distraction.

Return