Critiquing Code Comments
I am assuming that if you are reading this article, you are writing PowerShell code. I assume you are at least writing simple PowerShell scripts. Probably many of you are writing functions and modules. I also know that you understand the value of documenting your code. I’m sure you’ve heard this countless times. But what does this really mean? I always tell people to write PowerShell code for the next person. That next person could be you, who looks at the code again in six months and wonders what older you were thinking.
It is my opinion that well-written PowerShell code should read like a story. There should be a clear beginning, middle, and end. You should be able to identify the characters and easily identify their path through the story. You should be able to read the code from beginning to end and visualize the execution. Sure, there may be commands you don’t know. But this is no different than having to look up a new word in a novel. This is a good thing and how we expand our vocabulary. PowerShell is no different.
But in order to achieve this goal, the author needs to put in the work. If you follow the suggestions I have in this article, you’ll see that this doesn’t have to be a burdensome task. Documentation is more than adding a few comments throughout your code, and it is easier than you think.