My last post about comments generated a bit of conversation on Twitter, which highlighted my failure to communicate a few points.

My dislike for comments is predicated on two main concerns.  

First, if I find myself needing to leave a comment, I’ve accepted the fact that my code isn’t clear enough to explain what it is doing.  This could indicate a problem in my function or variable naming, or a need to refactor a dense block of code. 

Second, I’m committing to my code base or script a comment that does not actually surface during any possible way during execution.  As the script is updated, the chance that the comment will be updated to match the evolving functionality is very unlikely.

Are Comments Help or Documentation?

First and most importantly.. comments used as a convention to deliver help (like PowerShell’s Comment Based Help) are not what I’m referring to.  Other comments that fall into this category are things like javadoc or xml comments in c#.   Those use the comment syntax to deliver documentation end user of the code.  Since these comments are used exposed (either at run time in the case of comment based help, or at document generation time), there visibility is higher and the chance of staying up to date are much more likely.