The act of software development is challenging on all fronts. Not only is the task of programming often fraught with hurdles, when someone is confronted with working on someone else’s code that doesn’t make use of comments, but that job is also made exponentially more difficult.
Think of it this way: Imagine being given all the ingredients to bake bread, but no recipe. You know the dry ingredients go together, but you might not know the amounts of each. The same thing holds true with code comments that can help serve as a sort of brief on how a programmer used a function or how something was changed to meet a certain challenge.
Code comments are critical for efficient and effective programming. Joel Spolsky (StackOverflow co-creator) once said, “It’s harder to read code than to write it.” Why is that so true? Part of the reason is poor commenting. When developers don’t comment on their code, it becomes next to impossible to decipher what’s going on. But with a solid road map of comments, that miasma of code is much easier to understand.
So, for those who are looking to help their developers improve their work, what are the do’s and don’ts of code commenting? Let’s take a look.
Do 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 to communicate their intentions and actions to other programmers. If one programmer includes well-written comments in their code, they are communicating with all of their collaborators as to what’s going on with their work.
Do Write Comments With Another Person in Mind
Along the same lines, your developers should consider that comments should be written with other people in mind. This tool isn’t just about leaving themselves notes about their work but helping others to decipher what they’ve done.
One of the main purposes of comments is to help other programmers understand what is happening within the code. This means your developers must write such that any developer could open their work and understand what’s happening.
Do Work to Eliminate Confusion
Code commenting should serve the purpose of eliminating confusion from code. It’s not about showing off their work, but about simplifying the process of collaboration and understanding. Making their work clear and obvious should be the number one goal of code commenting.
This also means your developer’s comments should also be very clear and concise (and not add even more confusion to the mix).
Do Provide Links to Original Source of Copied Code
If your developers copy code from other sources, they should always leave links to the original sources. Why? Because whoever follows in their footsteps might need to understand why they used that piece of code and what its original intent was, and may even need to contact the developer of the copied code.
Do Add Comments When Fixing Bugs
Code comments aren’t 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, however, your developers shouldn’t be writing lengthy howtos in the comments but should be precise and efficient in their wording.
Do Make Use of Code Annotations or Tags
To help make things concise, your developers should make use of code annotations and tags. For example, @desc will be a description, @param will be a description of parameters, @returns describes the returned output, and @throws describes possible error types. Most developers should have a solid grasp of such annotations and tags. If not, make sure they learn about them.
Do Write Comments While Writing Your Code
Instead of your developers going back after the code is complete to insert comments, they should write them as they go. This can avoid a lot of problems. First, it’ll avoid a developer forgetting why they did something. Second, if something happens to a developer in the middle of the project, the comments are already 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 they shouldn’t comment on every single thing. Developers shouldn’t comment on the obvious. This mistake happens a lot with new programmers who feel as if they have to document everything they create along the way.
To help with this, have your developers consider if what they’re writing follows widely-accepted conventions and syntaxes, which means it probably doesn’t need a comment.
Don’t Use Comments as a Replacement for Documentation
Code comments and documentation are not the same things. You don’t want developers using comments as documentation because the code could wind up being way too long (and confusing) and causes unnecessary work. This happens a lot because developers hate writing documentation.
Code comments are there to explain specific functions and approaches, not to describe how something works in detail. If your developers are adding extraneous information in their code comments, you need to stop that behavior before it gets out of hand.
Don’t Refer to Other Comments in Your Comments
If your developers are referring to other comments (or even other documents), they’re giving other developers more work than necessary. Consider this: A developer places a comment within the code that refers to another comment. This means a developer who follows that person will then have to search through the code to find the referred-to comment. That’s too much work.
Instead of referring to another comment, your developer should spell out what they need to say (and do so efficiently). The goal should be to give less work to others, 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 into your developers early on, you can be certain anyone can pick up another developer’s code and know exactly what was done, why it was done, and how it was done.
