Commenting on code is supposed to be useful and help the readability of your code. The purpose behind commenting is so that someone other than the original developer would later be able to step in and understand the code. The problem with commenting: it’s often done poorly and ends up being a pointless distraction. A better way to make comments is to think more about what the code is ‘supposed’ to be doing. If comments enable us to know what the code is supposed to be doing, we have the ability to fix bugs where the code isn’t matching up with its purpose. Stick to best practices when commenting in your code to make it worth your while!
What NOT to use Commenting for:
Comments are not training wheels for code that is poorly written, or an apology for poorly written code. Just because you can write a comment in plain english does not mean writing convoluted code is acceptable. This is poor use of commenting, and while there’s nothing wrong with apologies, there is something wrong with what you’re apologizing for!
We don’t need to see someone’s name or initials in the code tagging lines. A version control system will show who was responsible for lines of code. Names just add time, money, and really no value whatsoever. Get over yourself.
Explaining How Code Works
This isn’t developing 101. As mentioned, comments should explain the intent of the code, not the ‘how’ of the code. Explanations are a waste of time/ or an indication of poorly written code.
To Do Lists
This one is tough. It may be useful to have some TODO comments in very early development, but after a year or more… what are you doing? Using comments in excess as to-do lists is a recipe for a pile of technical debt.
Do you not trust your version control, or not have version control? Well, you should always have version control because adding dates and change notes clutters up code, and imposes an unnecessary duty on other programmers. Or maybe people who do this are just code hoarders? Not sure, but it’s a waste of your time.
Comments take time, and time is money. So they’re incurring costs to write, but they have no impact on runtime behavior. The existence of comments is solely for the reader, so writing comments is only justifiable if it helps the reader enough to reduce their time spent reading code.
Developers tend to do a poor job of maintaining comments. Comments are usually neglected when source code is updated because there is no standard of maintenance. That leaves comments at the discretion of the individual developer. There’s also the fact that comments are just that — people’s opinions on something. Sometimes a developer is frustrated, or misunderstood the code entirely and explained it in a way that further misleads a reader. Sometimes a bad comment is worse than no comment at all.
When & Why to Use Commenting
It’s impossible for code to be completely self-documenting, but the goal is to minimize the amount of comments with elegant code and use comments for good, not evil. So as for the question of how many comments to put in: too many make the code tedious to maintain, and the comments will soon be out of date. Too few? Well that’s the goal, but too few can sometimes mean comments aren’t very useful. Strive for balance, but always ensure utility.
Communicate What Code Should Be Doing
Developers make an effort to create readable syntax, but syntax is derived ultimately by the compiler or interpreter, not the original developer. Thus, the point of commenting is to communicate the intent of the code functionality. When reading code, it’s obviously difficult to discern what the code is actually doing, so a comment is very useful when going back to make changes, fix bugs, etc… Comments must be written clearly, so another developer can easily understand the intent.
Comments Are a Nod to Team Efforts
Think the Golden Rule. How would you want a comment written to understand unfamiliar code? Your code, syntax and structure of your comments should be logical, efficient, and effective. Your intent should be apparent on the first read through both visually and logically. Well-commented code is a matter of respect for the other developers who will have a part in your code present and future.
Comments Draw Attention to Problem Areas
Comments can be used as warnings; good use of comments includes mentioning areas of concern for future developers or testers. That doesn’t negate poorly written code for things like boundary conditions, valid argument ranges, or corner cases. There are scenarios when these ‘warnings’ are very helpful in building well-designed code, but adding a comment does not give you a pass on code quality.
Comments have their time and place in code, but the best comment is no comment at all! In other words, your code should speak for itself. However, no code is completely self documenting. Commenting does not add inherent value to your code, and it does require extra time and space. To extract maximum value from commenting in building and expressing intent to future developers, comment clearly and wisely.
Commenting on this blog post, however, is a veritable free for all. Have at it!