A comment on the Clearest Code Challenge inspires this post.  In particular the bit about how someone can figure out the code if it's commented, “no matter how crap the code is”.


Comments are smelly.  Really.  From Ward's Wiki: “Refactor the code properly and you won't need comments.”  My OO Jedi Master insisted I detail the implications while blindfolded & blancing an LCD panel on my nose.  There may be typos.

  • If a comment & a line of code both say the same thing, there's duplication in your source code.  You now need to maintain both.  If you forget to update one of them, it's now even more confusing.
  • What happens if you remove the comment and extract the line of code into its own method? 
    • Does the comment become the method name? 
      • Does the new method look useful elsewhere? 
        • Does that new method belong on a different class?
          • What if you create a new class?  What else goes on it?
  • Can you change the way you wrote the code so the comment isn't necessary?  Do this now.
  • When you remove comments that duplicate teh code, you can now focus on commenting the whys.
  • See also CommentCostsAndBenefits
  • If you think code needs clarification, don't leave it be.  If you can't refactor now, add a comment so you remember that it needs refactoring later.  (To quote Kent Beck, “Never interrupt an interruption.“)
  • Comments don’t stink.  But they should catch the attention of your nose.