Powershell Best Practice #5: Avoid excessive comments (over-commenting)

By | May 22, 2015

Best Practice: It is recommended to avoid excessive comments (over-commenting).


The code should be enough self-explanatory so that no comments at all are needed. I would recommend to refactor the code instead of adding comment to the code logic.

For example, if you have block of code of 15 lines and you want to explain what does this block by adding comments, it would be better (instead of commenting) to create 3 methods of 5 lines with understandable name (Get-Header, Get-Title, Get-Body).

Commenting the code logic is usually considered an anti-pattern because it means that your code is not self-explanatory.

The following code is definitely “too much” commented and makes too difficult to read.

You don’t need to explain that you are getting to retrieve the list of services before the cmdlet “Get-Service“, it is already self-explanatory.

Now, see the difference with that one, much clearer to read, extra comment have been removed:

Important: Do not confuse with “Comment-Based Help (CBH)” which is useful.


Leave a Reply

Your email address will not be published.