Avoid Comments

A comment is a way to put a piece of not-code in your code.

In general, there are 4 type of comments:

1. Legal Headers

A file begins with commented lines which detail the license under which the code can be used. This is a staple of open source software. Sometimes closed source software imitates that, even though that leaves the question who it is directed at.

2. Coupled Documentation

Documentation comments in C# provide a way to deliver API documentation together with the code; in a way that allows IDEs to display tooltips for… well, anything, really.

This requires the documentation to be solid, as one wrong comment – be it outdated, a typo or something else – can do more damage than 10 undocumented methods.

3. Explaining unintuitive code

Sometimes a library has some weird bug and the workaround seems like it would do something else, or is doing something unnecessary. In that case a comment can explain why something is being done the way it is being done.

This can also happen for your own code, but in that case it tends to be a sign that we should use a different approach.

4. …this

// Gets the product
public void GetProduct()

Or any variation. If you’re doing this, you might just as well do

// Comment for the method GetProduct():
// Gets the product
public void GetProduct()

This provides no additional value at all.

Next Article: Avoid Brackets for Conditionals