In this post, we continue with the examples of bad comments.

Position Markers

Sometimes people put a comment marking an important place in a file, or to separate the sections (variable definitions, methods, etc.) inside the file. This is something that should only be done in special cases, since overuse can just make the comments become background noise.

Closing Brace Comments

Comments beside closing braces is a bad sign, because it means that you have a lot of nested blocks in your code, or your functions have too many lines of code in them. This probably means that the code is doing more than one thing and should be split into separate functions.

Attributions and Bylines

Including comments in your code that say who did what, shouldn’t be necessary any more. This kind of tracking should be the responsibility of your version control software.

Commented-Out Code

Lines of code that have been commented will very quickly pollute your code. Sometimes you want to make a copy of the code that was working before, as a safety measure if any of the changes you make introduce a bug. With version control systems, you should be able to see the old code if you need to.

HTML Comments

Don’t write comments in HTML Format, or other formatting options). Comments are for the code in the file, and they should be easy to read.

Nonlocal Information

Comments have to refer to the code that is near them. Don’t write comments about things that are global, or things that they have no control over, because if they change, the comments probably won’t be updated.

Too much information

Comments should be concise, and just as long as they have to be.  If you want to offer a way to have information that is related, but not necessary, a link to the extra information is a good option.

Inobvious Connection

The relationship a comment has to the code it refers to should be obvious. Give enough information to make sure that anyone that has to maintain the code (and a decent understanding of the system’s domain) will understand the comment.

Function Headers

If you have written your code well, then all functions should have a clear and descriptive name, be fairly short, do one thing, and the parameters names should tell you clearly what they expect. All this details should make it unnecessary to write a comment at the function header explaining what it does.

This brings to a close our discussion about comments.

Constantly challenge yourself to try to write code that doesn’t need comments.