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.
I totally agree with June’s description of the difference between comments and help. What I disagree with are that comments should be used to describe how and why it works. This leads to the next topic.
Should Comments Be Used To Understand Advanced Code?
There seems to be a feeling that code cannot be understood without comments. There are situations where a comment (or comments) can be helpful in clarifying why a choice was made, but a comment should be the LAST resort.
Let’s look at the example June (@juneb_get_help)provided. (I’m not picking on June, she’s a great person and her work and support in the PowerShell community has been much appreciated over the years. She was just kind enough to disagree with me and share her thoughts on Twitter.)
She referenced one of Joel’s (@Jaykul) scripts in support of his IRC bot.
As an option to comments, I’d suggest a bit of refactoring to clarify intent. For example, breaking out some of his parameter token parsing logic into separate functions, rather than having one longer block of code. (I’m not picking on Joel’s code here, I’ve done the same previously and I’m still working to fix public examples that I have. His is just the example that June pointed out.)
Rather than littering already dense code with additional comments, I’d start to pull blocks of code out into separate functions.
As Kendal (@SQLDBA) points out, complex decision trees can be difficult to follow in a large block of code or complex algorithms. I definitely agree that following complex decision trees warrants some additional help. Here again, though, I’ll look to refactor first if I felt the need for comments and clarification.
Kendal also raises a valid point about commenting why you didn’t do something. Comments should be an exceptional case, for exceptional situations. This can definitely fall into that case.
What Is Considered A Comment?
I’ve got mixed opinions about the region/endregion statements. I find them useful for grouping sets of functions. Once I see region/endregion inside a function, I start getting a bit nervous. That segment cries out for refactoring.
As Chris (@LogicalDiagram) notes, in PowerShell, Write-Verbose and Write-Debug (in addition to Write-Warning) are great for providing additional streams of information that can provide context and logging throughout an operation. These are not comments. They can serve some of the purposes of comments. They differ from comments in that they provide actual runtime value
Regardless of the caliber of the comments, they are exceptional circumstances and should be treated as such. Alternatives, such as refactoring or adding a logging statement should be considered first. If those don’t make sense or cannot add clarity, then and only then should be look to add a comment.
Sunny (@sunnyc7) catches my drift. The code should speak for itself. Verbose and debug logging adds context and enhances the runtime experience.
Where Does That Leave Me?
I still think comments indicate a “code smell”. In striving for cleaner code, we should seek to minimize the need for comments by writing clearer, more readable code. I want to thank everyone who cared enough to share their thoughts on Twitter and via comments to the previous blog post.