Scripting Games Event 2 Commentary

Put your comments at the top of your functions!

According to the about_Comment_Based_Help you can place your comment based help in any of three locations:

  • At the beginning of the function body.
  • At the end of the function body.
  • Before the function keyword. (There can not be more than one blank line between the last line of the function help and the Function keyword.)

Generally the third option is used most of the time. However during the games I saw a lot of people put the comment-based help at the end of the function. While technically a valid place to put the help I dislike it very much.

Sure comment-based help is technically used for displaying help from within PowerShell but it also has a second purpose. It also serves as inline documentation for the functions. When reading a function to understand it comment-based help provides documentation and insight into what the function does. Putting it at the end doesn’t make it very useful for this purpose. Put it at the top.