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

By | May 22, 2015

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

Explanation:

In most of the cases, the code should be enough self-explanatory so that no comments (or very few) are needed.

The following code is definitely “too much” commented and makes that almost 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.

You should add comments only when it is necessary and when it makes real sense.

Adding too much useless comments is a waste of time (the time you spend to write comments is time you don’t spend for your code). Cmdlets in Powershell are enough easy to understand with the name convention (Verb-Noun).

Moreover, it makes the code harder to read when there are too much useless inline comments.

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 very useful and recommended. That makes sense.

 


previous-buttonnext-button

2 thoughts on “Powershell Best Practice #5: Avoid excessive comments (over-commenting)

  1. Pingback: Powershell Best Practice #6: Use singular noun (not plural noun) | Powershell Guru

  2. Pingback: Powershell Best Practice #4: Use CIM cmdlet (not WMI cmdlet) | Powershell Guru

Leave a Reply

Your email address will not be published. Required fields are marked *