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]