Many programmers, both good and bad, dislike writing comments. When working on a team, lack of comments will eventually lead to lost productivity due to time spent tracing and re-learning. The problem continues to get worse as revisions are made over the life-cycle of an application. This can be especially true in larger teams where people come and go and/or work is outsourced. However even if you’re the only programmer working on the code, it’s easy to forget why you did something months or years ago.
It’s my opinion that great programmers comment their code even if they’re the only person working on a project. Not only does the small investment pay off later, it’s a simple habit that forces you to plan and proof-read your own work. A poorly conceived function will become more apparent as you try to explain your thinking in the comments. JavaDoc can be written before the code itself which helps to flesh out ideas before writing a lot of code.
To write effective comments, I try to find a balance between two things. First, that someone might be reading only the generated documentation without access to the source code. Second, comments that simply repeat the function and argument names are not helpful. Great comments may briefly explain *what* a function does, but more importantly it should explain *why* the function exists.
Take this function as an example:
/**
* this function adjusts the print margins
*/
private void adjustPrintMargins(int x, int y) {}
The comments for this function are basically worthless because it doesn’t give any information that wasn’t already apparent. The purpose of the function is fairly obvious and you might even thing that it could get by without comments. Judging by the function name it obviously adjusts the print margin and x & y are an increment of some sort. The function itself is possibly simple, but there’s actually a lot of vagueness. This would probably require looking into the source code to figure out what it really does, which takes time. Here’s the same function with some better documentation:
[Update: several people have argued about this next example because I included the calling function Printer.preRender() in the comments, however below I also write "If this function was called from a lot of places, though, it might be better to describe when it's called more generally, perhaps mention the circumstances or types of objects that would call it." The idea is not to put in content that will be impossible to maintain, but rather to put in information that helps other coders to understand why and how to use this function, to show this info in auto-complete and to auto-generate documentation.]
/**
* Adjusts the margins of this document based on the printable area
* allowed by the selected printer. This function is called by Printer.preRender()
* immediately before the document is spooled for printing.
*
* @todo: add validation to ensure x/y are legitimate values
* @param int the minimum horizontal margin (in pixels) supported by the printer
* @param int the minimum vertical margin (in pixels) supported by the printer
*/
private void adjustPrintMargins(int x, int y) {}
Oh brother, who wants to type out all of that garbage, right? Well if you’re using a decent IDE it would have auto-generated all of the formatting and @params as soon as you typed /**. After that it took about one minute to type the actual text.
The comments above give a brief description of what the function does, but it also clarifies some of the vagueness and gives a little more detail about *why* the function is necessary. Another important detail is that it mentions *when* this function would normally be called – by another function Printer.preRender(). (If this function was called from a lot of places, though, it might be better to describe when it’s called more generally, perhaps mention the circumstances or types of objects that would call it.) Lastly, there’s a TODO in the comments which could indicate some part of the functionality that isn’t fully implemented or isn’t as clean as it could be. This didn’t take much time to type, but there’s a lot of really helpful information that could allow you to utilize or refactor this function with a little more confidence. Without these comments it might be easy to figure out what the function does, but perhaps no so easy why it is necessary. You might have to set breakpoints and trace the code backwards to figure that out. Turning on the debugger just to figure out why a particular function is called can waste a lot of time. It might take an hour to trace the code backwards, whereas it only took about one minute to write the comments.
Auto-complete in Eclipse w/ PDT Plug-in for PHP
The comments themselves are important, but learning to write proper JavaDoc gives you even more added value. Even if you aren’t writing in Java, it’s used as the basis for just about every language. Of course you can use any number of open source tools to generate nicely formatted documentation. Additionally many IDEs will parse javadoc and display it when auto-completing functions. Even the best programmers don’t remember the arguments for every function they’ve ever written. Having auto-complete display documentation for you inline as you type will pay off again and again, saving you huge amounts of time.
In my opinion it also depends on the function/method you are coding. I am a strong believer of short (max 20 lines) methods. They should always be small and do just one thing you can easily trace back.
Of course it’s not doable all the time. Then you must fragment your methods into smaller parts and comment them, of course.
In the end I have some nice maintainable code due of the fact I only have short methods, with only few comments.
What IDE is that screenshot from?
hey eqewrt – the screenshot is some PHP code in Eclipse with the PDT plugin installed.
A good comment is certainly a useful tool. But, IMO it is even more important have well factored and readable code – a well chosen code name for a function and its parameters can give as much information as a comment. Another problem is code that is commented out – I wrote a rant about that recently
When I’m in charge there are to be no comments more than 2-3 lines long. If more documentation is needed the coder should create an actual documentation page and place a link to that page as the comment.
@George and @Technikhill – I couldn’t agree with you more that code should be well organized, thoughtful and divided into small blocks. No amount of comments will make up for some really crappy code! I do feel that the habit of writing javadoc as you code improves quality because it forces you to review and clean as you work.
I still think comments are important even with short functions. It’s rarely a problem to look at some code and not be able to figure out what it’s doing. The problem is usually figuring out *why* a certain function does something. I started off writing the post with that though in mind.
I don’t think a lot of useless comments are good, but tossing out the baby with the bathwater probably isn’t the answer. It is a challenge to write great comments, but I think a good rule is to explain *why* rather than *what*
@jkovar
hey jkovar, I’m a proponet of the theory that a good developer is a lazy one – meaning he/she doesn’t like to do things twice. I’m happy with 2-3 lines if that’s all that’s necessary to get the point across. But maintaining a separate repository of documentation sounds like a lot of work to me!
If you’re writing an API that will be used by other teams then you usually need to provide some type of documentation, possibly including examples. javadoc already has standard formatting for all of these things and generates fantastic html-based documentation so, for me, it’s simply the laziest choice.
Not to push my own code, but here’s some documentation that was entirely auto-generated in about 15 seconds: http://phreeze.com/docs/ If it weren’t for javadoc comments I can guarantee I’d have never gotten around to writing documentation. My comments are by no means perfect, but I try to at least put a little something for every function with more detailed information for functions that seem to require it.
Also, my preferred IDE (Eclipse) minimizes each javadoc block into one line with a little button to expand it, so you don’t have to see any of the comments unless you expand the block. Along with other javadoc-related features, it just seems like the easiest way for me.
Thanks for stopping by!