Last week I was working with a Java library for manipulating SVG’s. With the library came a Javadoc, but when I looked through the Javadoc, I was surprised to find that none of the methods had any explanations. Classes were shown as well as the methods that belonged to each class. But what did doScale() do? What was the purpose of SVGAbstractTranscoder? None of this made sense, and while a “getting started” guide was provided, it wasn’t thorough and only explained a few simple tasks, none of which helped me do what I was trying to. Long story short, I had to move to a more well-documented library, and though it has less features, I at least could figure out how to use these features as the documentation was vastly superior.
Comments are immensely beneficial to anyone that is going to be dealing with your code, including yourself. There are many places where comments are helpful, including those describing a method, those describing class properties, those describing classes, and those describing the purpose of a block of code. Of those listed, I feel commenting a method is the most beneficial. Object-oriented programming (OOP) naturally tends to have many method calls across many different classes, and being able to find your way around and determine the expected input and output of a method, but also the purpose of a method can be a lifesaver. Even one brief sentence can help someone out that would otherwise have absolutely no clue what this method you wrote is for. Not only do comments help you later on down the road, after you’ve written the code and possibly forgot what a method was for, but it has the immediate benefit of making you think, “what is the purpose of this method?” If you comment methods before you write the implementation, you have a “definition” of the method, and when implementing your method, you’ll be able to tell if the purpose of the method is becoming fuzzy or if the code you’re writing is spot on with your original intentions of writing the method.
It is also important to note that most modern IDE’s have the ability to parse through comment blocks above methods and the better the comments, the better smarter the code completion will be. For the purists, some IDE’s allow you to throw errors at compile-time if a method is not commented, a feature that I sometimes find a burden, but more often than not has led to me writing better code than I would have otherwise.
Some feel that well written code doesn’t need comments, and some (I don’t get this logic) feel lots of comments are bad because it demonstrates that the code is not self-descriptive. This is just plain wrong, well-documented code rarely, if ever, means code is sub-par. In fact, I would go as far as to say the opposite is true, if I see good comments, I get that piece of mind that the author of the code knew his intentions well and planned out the code well enough to be able to define a purpose for each method, each class is carefully targeted and named for a specific purpose. If I saw a library with 500,000 lines of code, I would honestly be pretty scared of the stability and robustness of such a library.
Lastly, if you don’t want to take my word for it, look at any open source code library. I’d be willing to bet comments are poured liberally throughout the entire library. It’s not uncommon for the comment of a method to be longer than the implementation of the method. There is such thing as too many comments, but too much is better than not enough.
So, in conclusion, don’t be afraid to use comments, they’re your friend.
