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.
@Jaykul @StevenMurawski Help tells you how to use it. Comments tell you how/why it works. Reading commented code is the best way to learn. — June Blender (@juneb_get_help) February 14, 2014
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?
@StevenMurawski I respectfully disagree. How do you understand intent of advanced code w/o comments? e.g. http://t.co/p312Fl0ECn by @Jaykul — June Blender (@juneb_get_help) February 14, 2014
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.
Not all code requires comments to be instructive @juneb_get_help, as @StevenMurawski says. Was my module confusing for missing comments? — Joel Bennett (@Jaykul) February 14, 2014
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.)
@Jaykul @StevenMurawski Joel, it's a great example of a complex script that requires comments to understand the intent and coding choices. — June Blender (@juneb_get_help) February 17, 2014
Rather than littering already dense code with additional comments, I’d start to pull blocks of code out into separate functions.
@StevenMurawski @jsonmez I think MOST code is pretty straightforward. Where comments help are in understanding complex decision trees. — Kendal Van Dyke (@SQLDBA) February 17, 2014
@StevenMurawski @jsonmez …and in understanding complex algorithms. — Kendal Van Dyke (@SQLDBA) February 17, 2014
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.
@StevenMurawski @juneb_get_help @Jaykul One more perspective - comments also good for explaining why you DIDN'T do something. — Kendal Van Dyke (@SQLDBA) February 17, 2014
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?
@StevenMurawski so are you saying no to #region #endregion? Those blocs are amazing? — Jason Morgan (@RJasonMorgan) February 14, 2014
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.
@StevenMurawski Also need to ask, Write-Verbose and Write-debug, good code uses them as comments. Does that fall into your bad list? — Jason Morgan (@RJasonMorgan) February 14, 2014
@StevenMurawski @RJasonMorgan I like Write-Verbose, because all you have to do is append the -Verbose common switch parameter :) — Trevor Sullivan (@pcgeek86) February 14, 2014
@StevenMurawski @RJasonMorgan Agreed - came into the middle of the conversation. Verbose and Debug should not be code comments. — Trevor Sullivan (@pcgeek86) February 14, 2014
@pcgeek86 @StevenMurawski they are cetainly a type of comment, in that they announce what the code is doing in plain english. — Jason Morgan (@RJasonMorgan) February 14, 2014
@RJasonMorgan @StevenMurawski @pcgeek86 Verbose and Debug are for communication with the user. Using them for comments isn't as helpful. — Chris H. (@LogicalDiagram) February 14, 2014
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
@pcgeek86 @StevenMurawski so I think if you pointed out that the caliber and/or type of the comments matter you'd have a stronger point. — Jason Morgan (@RJasonMorgan) February 14, 2014
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.
@RJasonMorgan > I think the intent behind the article was to let your code do the commenting. @pcgeek86 @StevenMurawski — Sunny Chakraborty (@sunnyc7) February 14, 2014
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.