The art of commenting

Is commenting your code a waste of time, or programmer gold?

Ask any developer what programming task they enjoy least, and odds are you’ll hear “documentation” as an answer. After all, you came here to write code, didn’t you? Who wants to write boring text about the code? In fact, documentation is the grease that keeps the development process moving — good documentation benefits your co-workers, the users, and maybe even you. And the most basic form of documentation is the comments in your program itself.

Yes, Comments Really Are Important

In the beginning of your learning process, when you’re writing simple programs that you can debug by hand, comments seem unnecessary; you can figure out what your code does by reading it. When the code starts to become more complicated, though, you’ll depend on the comments. If you spend some time away from the code — weeks, days, sometimes even hours — you’ll find that what you thought was obvious and transparent code when you wrote it is now completely incomprehensible. Things get even worse if you need to work with somebody else’s code; unless you can read minds, the comments become essential to determining what the other programmer is thinking.

Just about every language has some form of comments (if you know one that doesn’t, tell me in the comments below), and they’re usually pretty easy to recognize. Most languages support both in-line comments, for quick notes, and longer block comments, for more detailed information. The exact syntax depends on the language, but if you’re using an IDE with syntax highlighting, the comments are usually easy to identify by color. Usually comments are prefixed by a special character; for example, in C++ or Java, in-line comments look like this:

Some languages, like Java, have tools that support turning your comments into separate documentation for your code. Which means that you should make sure your comments are quality.

What Needs a Comment?

Of course, if you try to explain every last thing your code is doing, you’re going to end up with more comment than code. So what requires commenting? In part, it depends on the experience level at which you’re writing your code. For example, if you’re just starting out, you might include a comment like this:

That’s not a particularly useful comment, though — it just repeats what the code itself says. If you’re a beginner, that might be helpful, but once you have a little experience, you won’t need comments like that.

The big mistake that example makes is that the comment explains how the code does something, rather than what it does, or why it does it. For example, suppose the assignment was something like this:

That’s more useful. Because you’re now getting the number of students from a function, some explanation is necessary to tell readers exactly what the function does. In this case, you know that the function only returns the number of registered students, as opposed to all students in the school. If the function accessed a database to get the count, you might include some information about the database in the comment.

Better still, though, would be to include an appropriate comment with the function itself, perhaps something like this:

This comment tells you what you need to know about the function without requiring you to read the code. It tells you what the input parameters of the function mean, and what the expected return value is. It also tells you that the code will raise an exception (an error) if a bad course number is entered. Notice that the comment doesn’t say how the number is determined; that’s not critical to being able to use the function.

Most developers endorse commenting your functions with this sort of information. Depending on where you work, what to comment and how may be a matter of policy. If you’re working on a project with many other developers, having a consistent format for comments saves time and frustration for everybody.

Isn’t there Another Way?

As always with matters of programming fundamentals, there’s a counter-argument. That school of thought runs that if you follow “readable code” practices, such as choosing clear and obvious variable and function names, you don’t need documentation, because the code documents itself. That’s a great ideal, but I see no harm in writing readable code and still including comments to make things easier. It’s always going to be easier to read a statement of the programmer’s intent in English than it is to read through the code, even for experts. You can argue that writing comments is a waste of the programmer’s time, which could be better spent writing code. Maybe it’s because I’m a technical editor, but it seems to me that taking time to make sure other people can understand your code is always time well spent.

tags: , ,

Get the O’Reilly Programming Newsletter

Weekly insight from industry insiders. Plus exclusive content and offers.