This week I noticed an article on comments in PoSh over at Simple Talk. It's a nice look at the topic from Greg Moore and discusses the various ways that you can comment in the language. Since these scripts are often shared in a corporate environment and because they may outlast your tenure, it's a good idea to include comments in your scripts and functions.
The idea with PowerShell is similar to what you get from docstrings in Python. Since many people can script and build modules, being able to get some help and understanding of the code is important. Even for the modules I write, I may use them for some time and then put them down. When I go to use the same cmdlet or function again, I might not remember all the parameters or what I was thinking. If you've ever had to dig into code to understand what is happening, you quickly learn to appreciate those well documenting help strings.
You may quickly learn to despise those that don't write them well or even forget to include them at all.
Writing a useful comment is a bit of an art. The author often needs to put themselves in the shoes of a less skilled individual, or maybe one that is context switching and needs to quickly understand what the code is doing. Not necessarily exactly how it works, but what it is supposed to do. This helps us decide if we can use the code quickly, or if we might need to dig in further.
In the article, Greg points out some nice additional comment items, such as requirements for the module to run. These are the types of quick enhancements to code that greatly improve its useability for others. I'd highly recommend everyone learn about comment based help in PoSh, docstrings in Python, and other valuable commenting techniques in your language of choice.
Learning to write good comments is a valuable skill, one that your team will appreciate. Since most of us work on teams these days, those skills just might make you more desirable for that next promotion or even a new position when word gets out. Practice becoming a good comment writer.
