Code Comments: Pros and Cons

Software development is a complex task from all perspectives. Not only is programming often fraught with difficulties when someone encounters work on someone else's code that lacks comments, but that work becomes exponentially more complicated.

Think of it this way: Imagine you are given all the ingredients for baking bread, but no recipe. You know that dry ingredients go together, but you don't know their quantities. The same can be said for code comments, which can serve as a sort of summary of how a programmer used a particular function or how something was changed to solve a specific problem.
Code comments are crucial for effective and efficient programming. One of the founders of ESK Solutions once said, "Reading code is harder than writing it." Why is that? Partly because of poor commenting. When developers don't comment their code, deciphering what's happening becomes nearly impossible. But with a reliable roadmap of comments, navigating through this miasma of code becomes much easier.
So, for those looking to help their developers improve their work, what are the "pros" and "cons" of code commenting? Let's take a look.

Use Comments as a Way to Communicate

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. When a programmer includes well-written comments in their code, they are effectively communicating to all their colleagues what is happening in their work.

Write Comments with Others in Mind

Similarly, developers should consider that comments should be written with other people in mind. This tool is not just for leaving yourself a note about your work, but also to help others decipher what you have done.
One of the main purposes of comments is to help other programmers understand what is happening in the code. This means your developers should write in such a way that any developer can open their work and understand what's going on.

Work to Eliminate Confusion

Code commenting should serve the purpose of eliminating confusion in the code. 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 when commenting code.
This also means that your developer's comments should be extremely clear and precise (and not add further confusion).

Provide Links to the Original Source of Copied Code

If your developers copy code from other sources, they should always leave links to the original sources. Why? Because someone following in their footsteps may need to understand why they used that code, what its original intent was, and even contact the developer of the copied code.

Add Comments When Fixing Bugs

Code comments are not only needed for original (or copied) code, but also for cases where your developers fix bugs. These comments should explain exactly what they did to fix the bug and why it was necessary. However, again, developers should not write long-winded "how-to" in comments, but should be precise and efficient in their wording.

Use Code Annotations or Tags

For brevity, developers should use code annotations and tags. For example, @desc is a description, @param is parameter descriptions, @returns is the return value description, and @throws is possible error types. Most developers should be well-versed in such annotations and tags. If not, be sure to acquaint them.

Write Comments While Writing Code

Instead of going back after finishing the code and inserting comments, developers should write them as they go. This avoids many problems. First, the developer won't forget why they did a certain action. Second, if something happens to the developer in the middle of a project, the comments are already in place, and someone can continue working without much trouble.

Don't Comment Everything

It's also important for developers to understand that they should not comment everything. Developers should not comment the obvious. This mistake is common among beginner programmers who feel they must document everything they create as they go.
To help with this, ask developers to consider whether what they are writing follows common conventions and syntax, meaning it likely doesn't need comments.

Don't Use Comments Instead of Documentation

Code comments and documentation are not the same thing. Developers should not use comments as documentation, as the code can become too long (and confusing), leading to unnecessary work. This often happens because developers hate writing documentation.
Code comments are meant to explain specific functions and approaches, not to describe in detail how something works. If your developers are adding extra information to code comments, you need to curb that behavior before it gets out of hand.

Don't Reference Other Comments in Your Comments

If your developers reference other comments (or even other documents), it means they are giving other developers more work than necessary. Consider the following example: A developer places a comment in the code that references another comment. This means the developer who follows will have to search the code for the referenced comment. That's too much work.
Instead of referencing another comment, your developer should clearly state what they need to say (and do so efficiently). The goal should be to give others less work, not more.

Conclusion

Code comments are as important as the code itself, as they help make everyone's work easier. If you can instill good commenting habits in developers from the start, you can be sure that anyone picking up another developer's code will know exactly what, why, and how something was done.