I have mentioned putting comments in your code previously on this blog - Encouraging Comments - but I have just happened across a blog where there is a function that does date manipulation and could be handy for a project I am working on. There isn't one piece of comment in the whole 50 lines of code. The function isn't described, or even attributed, the variables are not explained, the steps are not detailed and what could have been its saving grace, an example at the end is also missing. I am now having to work through different values for each variable just to see what it should be and how I can then use it to get predictable results.

For me, if there is a decent section of code at the end of a function or procedure that gives examples then that goes a long way to mitigate the crime of no comments anywhere else. In all of my production code there is a section at the bottom that show different ways of executing the procedure with a variety of valid values.

Someone new to the work can simply highlight the whole example section and press F5 to see the different returns. This lets them rapidly get to grips with the problem they are facing and resolve it. It also justifies the effort you put into your scripts, to make sure people can use them as they are intended.

Oh, the most unbelievable bit about the code I found online? It was from an MVP!