Code Comments

• August 18, 2009
• Brian Tarricone

I’m a bit of a minimalist when it comes to commenting my code. This is
probably in some ways a bad thing; code that is completely obvious to me
in its function may be difficult to understand for others, and I’m often
not so great at realizing this on the first pass.

So that leads me to the purpose of code comments:

The purpose of commenting your code is to inform readers of that code
what a section of nontrivial or non-obvious code does.

At least, this is my definition. Opinions differ, I’m sure. I might
also add to that a clarification: “readers” in this case may include
yourself. Code you wrote may even be incomprehensible to you if a
decent amount of time has passed.

From this definition you can also infer something else, that I believe
it’s unnecessary to comment obvious code. In fact, I’d argue that it’s
harmful to comment obvious code, because you’re making it harder to
follow, and you’re adding a barrier in front of the reader being easily
able to distinguish between trivial and nontrivial code at a glance.
You also increase the length of the code fragment, which may make it
more difficult to read and understand in its entirety (if you can’t fit
the entire fragment on one screen, you’ll have to scroll back and forth
to see the entire thing).

However, too often – very often, it turns out – I see things like
the following:

/* take a reference */
g_object_ref(object);

/* free string */
g_free(str);

And one of my favorites:

/* set the label text to "Time Left:" */
gtk_label_set_text(GTK_LABEL(label), "Time Left:");

(Yes, I actually have seen something very similar to that, though I
don’t remember what the label text was.)

How do these comments actually add anything useful to the file? Every
time I see one of these, a little part of me dies inside.

Now, the last one is just silly. Even someone who has never developed
using the gtk+ UI toolkit can figure out what that line of code does
without the comment. If you can’t, then a code comment there probably
isn’t going to be enough to help you overall in any case.

The middle one is equally silly, though it’s understandable that someone
might not know that g_free() is the glib equivalent of free(). However,
consider your audience: is an extra line of code for a comment really
useful here?

The first one is not quite so easy for me to dismiss. It presupposes a
few bits of knowledge:

1. Understanding of what reference-counted memory management is.
2. Familiarity with the “ref/unref” pair, as opposed to only being
   exposed to something like the OpenStep “retain/release” (or even the
   COM/XPCOM “AddRef/Release”) terminology.
3. At least passing knowledge of what a GObject is.

Now, for code that makes heavy use of reference counting, I think
presupposing #1 is not unreasonable. In this case, it doesn’t matter:
the comment as presented will not help you if you don’t know what
reference counting is.

Points #2 and #3 depend on your goals and potential audience. If you
think that a decent number of readers may not be familiar with the
“ref/unref” terminology, “take a reference” is probably enough to
generate an “oh, duh!” moment in the reader’s head. As for #3, unless
you intend your code to be able to act as a sort of GObject tutorial,
that is, something that people aspiring to learn GObject programming
might want to read, I think the comment there does not serve people
unfamiliar with GObject. Regardless, most GObject-using code will
probably be pretty confusing to someone who doesn’t know GObject, so
whether or not you should comment g_object_ref() is going to be the
least of your worries.

Now, I’m not going to claim that my code commenting is perfect… far
from it. I could certainly stand to sprinkle comments a bit more
liberally throughout my code. I tend to only comment public API (and
then just a description of what the function does, not how it does it),
and code fragments that are really nontrivial¹ and potentially hard
to understand.

But there has to be a happy medium somewhere. While too-infrequent
commenting can certainly make code harder to understand, I’d argue that
too-frequent commenting is worse. It’s sorta like “the boy who cried
wolf” in the sense that comments draw my eyes to them as a way of
saying, “pay attention! This bit here is important!” (or tricky, or
whatever). Overuse of comments just makes me start skipping over all of
them, useful or otherwise.

of comments. I generally prefer clear code over neat hacks, even if
the neat hack represents a reduction in lines of code or a moderate
increase in performance. If I write a section of code and then look
at it again and see that it looks too complex, I’ll usually try to
immediately rewrite it to be simpler.