PowerShell Great Debate: Can You Have Too Much Help?


In The Scripting Games this year, more than a few folks took the time to write detailed comment-based help. Awesome. No debating it - comment-based help is a good thing. 
But some folks felt that others took it too far. There were definitely scripts where the authors used, for example, the .NOTES section to explain their thinking and approach. Some commenters felt it was excessive, while others have pointed out, "wow, what if every programmer gave us some idea what the heck he/she was thinking at the time?" Some felt these extensive comments were just at attempt to get a better score by "convincing" the reviewer of an approach or tactic; others felt, "so what?"
So let's leave the Games out of this debate - in a production environment, where do you come down on extensive notes in a script? When is it not enough, and when is it going too far? Where's the value, and where's the annoyance?
[boilerplate greatdebate]

5 Responses to " PowerShell Great Debate: Can You Have Too Much Help? "

  1. Dave Wyatt says:

    It just depends on your target audience. Comment-based help is directed at the consumers of your function. It documents the interface, so to speak; what are the inputs, outputs and errors / exceptions generated if I call this function or cmdlet?
    Inline comments are directed at developers who may need to maintain or modify the function itself (documenting the implementation). This seems like the most appropriate place for comments that explain why you did something a certain way.

  2. Art Beane says:

    Actually, anything that is comment-based is focused towards developers who must actively search for it (using Get-Help). That doesn’t lessen the value of any help provided, though, and I don’t think there is any such thing as “too much”.
    One thing I’d like to be able to do is to have a brief summary (the Synopsis comment??) that shows up when hovering over the file name in Windows/File Explorer. Similarly, it would be helpful to see the complete comment based help for a script file without having to start Powershell. For example, to be able to see it in the file Properties right-click options.

  3. June Blender [MSFT] says:

    I have an obvious bias, but I don’t think you can have too much help. However, you can have help that is not really helpful, that is, help that is poorly organized, inappropriate to the audience, and difficult to understand.
    My pet peeve is help that is designed to impress, instead of instruct, including fancy (ambiguous) verbs, poetic passive voice (who is supposed to do what?), and examples that you can’t understand without a degree in computer science, home economics, and hieroglyphics.
    Help is most important in production scripts where someone’s job or product delivery might depend on the timely outcome. I try to think about what the people who run and maintain the scripts (two different audiences) need to know.
    BTW, all help doesn’t need to look like traditional cmdlet help. For example, the help for the scripts that assemble files for Updatable Help describe the module and it’s little quirks and features, and explain design decisions — why we used this parameter and call that other script. It also includes contact info in case someone is stuck.
    The best way to make sure that your help is helpful is to have lots of people review it and give you their honest opinion. Be sure to check for accuracy (dev/test), readability (writers/editors), and usability (release management).
    This really is a great debate. I’ll keep reading the responses. 🙂

  4. Cameron Ove says:

    Personally I love it when folks use the help facility within a function or script (synopses, description, parameters, examples, etc..) The more thoroughly they fill out those comments the better the help. I’m especially disappointed when I download a third party set of cmdlets that don’t have complete help (e.g. missing examples is very disappointing for me).
    However, if I understand this debate correctly, there is also the question of commenting your code lines within your function or script. I think that needs to be well though out. I’ve seen code, and even written it, where every line has a comment above it telling why that piece of code was written. Every time I’ve ever seen that I had such a difficult time following the logic of the code (even my own code after I came back to it weeks or months later). I think that a few lines of well thought out comments above a block of related code is better. It helps to understand what the block is doing and yet at the same time it allows for easier reading and following the logic of the block of code.
    The bottom line for me is that I think there can be too much inline help within your code, but the help facility that PowerShell provides can be jam packed full of information; the more the better, as long as you follow June Blender’s recommendation, “…make sure that your help is helpful…”

  5. SqlChow says:

    From a operational perspective, I think there is no such thing as too much help but, how much of it is useful is the guiding principal which determines its usefulness.
    I say this because, most of the times we end up owning or maintaining scripts, environments, projects etc that were managed by someone who may or may not be with the organization anymore. Commonsense dictates that I verify what the said asset is actually doing before using it.
    At this point the best case scenario is that there is cmdlet like help available on the script and the description/notes describe the business logic or have additional links to Wiki pages that need to be read before we can understand the choices made in the script.
    Not having any help comes in a close second because, you have your work cutout for you. You know you have a long day ahead of you; rollup the sleeves and start reading the script and start making notes of what you think it does.
    The absolute worst kind of help you can actually see in there is a description like so: “loop through a set of server from the file and change domain account passwords”. <–You don't say!
    I have to agree with June Blender's suggestion about not adding inline comments that are distracting or useless in nature.