Powershell Best Practice #5: Avoid excessive and useless inline comments

By | May 22, 2015

Best Practice: It is recommended to limit useless inline comments, unless it really make sense.

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

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

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.

In my opinion, 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 and useless inline comments

  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 *