Code commenting what to do and what not to do

The act of software development is challenging on all fronts. Not only is the task of programming often fraught with obstacles when one is faced with working on someone else's code that doesn't make use of comments, but that work also becomes exponentially more difficult.

Think of it this way: Imagine being given all the ingredients to make bread, but no recipe. You know that dry ingredients go together, but you might not know the amounts of each. The same goes for code comments which can help serve as a sort of summary of how a programmer used a function or how something was changed to address a particular challenge.

Code comments are essential for efficient and effective programming. Joel Spolsky (co-creator of StackOverflow) once said, “It’s harder to read code than to write it.” Why is this so true? Part of the reason is bad reviews. When developers don't comment on their code, it becomes nearly impossible to decipher what's going on. But with a solid comment script, this miasma of code is much easier to understand.

So, for those looking to help their developers improve their work, what to do and what not to do when commenting code? Let's take a look.

Use comments as a form of communication

One of the best things you can help your programmers understand is that they should use comments as a means of communicating their intentions and actions to other programmers. If a programmer includes well-written comments in their code, they are communicating with all their collaborators about what is happening in their work.

Write comments with someone else in mind

Along the same lines, your developers should consider that comments should be written with other people in mind. This tool is not just for leaving notes about your work, but also for helping other people decipher what they did.

One of the main purposes of comments is to help other programmers understand what is happening in the code. This means that your developers must write in such a way that any developer can open their work and understand what is going on.

Work to eliminate confusion

Code comments should serve the purpose of eliminating code clutter. It's not about showing off your work, but about simplifying the process of collaboration and understanding. Making your work clear and obvious should be the number one goal of code comments.

This also means that your developer's comments should also be very clear and concise (and not add even more confusion to the mix).

Provide links to the original source of the copied code

If your developers copy code from other sources, they should always leave links to the original sources. Why? Because whoever follows in your footsteps may need to understand why you used that piece of code and what your original intention was, and may even need to contact the developer of the copied code.

Add comments when fixing bugs

Code comments are not just for original (or copied) code, but also for when your developers fix bugs. These comments should explain what they did to fix the bug and why it was necessary. Again, though, your developers should not write extensive instructions in comments, but should be precise and efficient in their words.

Make use of annotations or code tags

To help make things concise, your developers should use code annotations and tags. For example, @desc will be a description, @param will be a parameter description, @returns will describe the returned output, and @throws will describe possible error types. Most developers should have a solid understanding of these annotations and tags. If not, make sure they learn about them.

Write comments when writing your code

Instead of your developers going back after code completion to insert comments, they should write them as they go. This can avoid a lot of problems. First, it will prevent the developer from forgetting why they did something. Second, if something happens to a developer mid-project, the comments will already be there, so someone can pick up where they left off without too much trouble.

Don't comment on everything

It's also important that your developers understand that they shouldn't comment on everything. Developers shouldn't comment on the obvious. This mistake happens a lot to new programmers who feel like they need to document everything they create along the way.

To help with this, ask your developers to consider whether what they're writing follows widely accepted conventions and syntax, which means it probably doesn't need comments.

Don't use comments as a substitute for documentation

Code comments and documentation are not the same thing. You don't want developers to use comments as documentation because the code can end up being too long (and confusing) and cause unnecessary work. This happens a lot because developers hate writing documentation.

Code comments exist to explain specific functions and approaches, not to describe how something works in detail. If your developers are adding extraneous information into their code comments, you need to stop this behavior before it gets out of control.

Do not refer to other comments in your comments

If your developers are referring to other comments (or even other documents), they are giving other developers more work than necessary. Consider the following: a developer places a comment in code that refers to another comment. This means that a developer following this person will have to search the code to find the mentioned comment. That's a lot of work.

Instead of referring to another comment, your developer should explain what they need to say (and do it efficiently). The goal should be to give others less work, not more.

Conclusion

Code comments are just as important as the actual code because they help make everyone's job easier. If you can instill good commenting habits in your developers from the beginning, you can be sure that anyone can take another developer's code and know exactly what was done, why it was done, and how it was done.