Whether or not to comment your code is a hotly-debated topic in the web and software development industry.
Many great developers believe that commenting your code is redundant and a waste of your time. Developers who hold this view are probably more inclined to believe that good code doesn’t require commenting. And that’s true, to an extent. Good code certainly doesn’t need commenting. But it could probably benefit from commenting.
Adding comments in code is actually a practice that, when done well, can have quite a few benefits. When writing code, comments provide an easy and effective way to note down the purpose of specific segments in your code on-the-fly. Simple snippets of code, or those in a short file, for instance, may not really require commenting, but it can still be helpful.
First and foremost, comments help the original author to identify parts of his or her code, which may sound unnecessary and redundant (you should know your own code, right?), but can actually end up proving very helpful. If you haven’t read through the code in a long period of time, your memory is likely to need jogging, and comments left by yourself can be a gentle way to ease yourself back to familiarity, even with your own code.
While it might not take a considerable amount of time to identify the purpose or workings of specific segments in your own code, you’ll probably find that (especially for big projects) comments allow you to navigate through the code at a much quicker pace. This cuts down on time spent scanning aimlessly for a small line of code you can’t easily locate.
And if a project is being maintained by multiple developers, using comments can actually provide a lot more benefit than nuisance. In fact, in team scenarios, comments can become quite necessary — much more so than simply including them for oneself. Collaboratively commenting code is one of the best ways, besides the presence of a separate documentation file, for teams or groups of contributors to identify the purpose of workings of different segments of code. It makes searching through the code much easier, and lays out the method that the original author used in clear terms.
Don’t get me wrong. The use of commenting can definitely become redundant. Using comments as a place for ‘waffle’, or over-explaining the purpose of the code, can be both a waste of time for the code author and their colleagues who will be subsequently reading (or wading) through it. Inevitably, there is a danger for this to result in a situation where it takes more time to read through the comments than the code itself, creating an entire separate problem.
So, in summary:
- Keep your comments short, concise, and to the point.
- Use good English, and avoid unnecessary waffle and ‘fluff’ in your comments.
- Keep comments organized, and don’t overuse them. There shouldn’t be more comment than code.
- Remember that it isn’t necessary to comment each and every line; that’s overkill.
- Keep your comments above sections of code that perform broad tasks, rather than for specific lines which can easily be identified.
If a line of code can be easily understood without the need for a comment, then omit the comment and invest that time in writing great code instead. If your code can’t be understood without a comment, try considering whether you’re coding efficiently and assess what could be changed.