Code Comments
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:
- Understanding of what reference-counted memory management is.
- 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
- 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[1] 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.
[1] It’s worth noting here that this point further reduces my volume 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.
Code Comments
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:
And one of my favorites:
(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:
- Understanding of what reference-counted memory management is.
- 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.
- 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 nontrivial1 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.
-
It’s worth noting here that this point further reduces my volume ↩
More Firefox 3 SSL Junk
Lately I’ve noticed a flood of Firefox 3-related posts regarding the new SSL error handling on Planet GNOME. It’s a little funny, as I was writing about this myself a little under two months ago.
Chris Blizzard posts in favor of the new arrangement, and points to an interesting post by Johnathan Nightingale explaining Mozilla’s position. Yes, agreed, Jonathan’s post is a good read, but the salient point is that the new UI is just awful from an average non-technical user’s perspective.
The extra clicks and somewhat abnormal flow (e.g. the need to click a button in the dialog to fetch the certificate) make it harder for the user to understand how to successfully add the exception. You might say that some false positives (i.e., users who fail to access a site that they really actually do want to access) is better than a user succumbing to a MITM attack, but I’m not sure I’d agree.
Equally importantly, the error messages make no distinction between the potential severity of the various SSL errors. For example, I’d say a self-signed cert on a site that you’ve never visited before is fairly low-risk. But a self-signed cert on a site that used to have a trusted cert would be a huge red flag. Domain mismatches and expired certs would fall somewhere in between. It’s hard for the average user to make an informed decision on risk/severity if they were to encounter both of these situations because the error messages and dialogs look exactly the same.
Addressing Johnathan’s main point about self-signed certs and level of security: as a highly technical/advanced user, I personally can say that, in the vast majority of instances where I encounter a self-signed cert, I really do just care about the encryption, and I don’t particularly care about the identity verification of the site that a trusted cert could offer. Now, Firefox probably shouldn’t use me as an example as a target user that needs protection, but that’s a data point nonetheless. I don’t care for things like: Bugzilla installations, my blog, accounts at sites like identi.ca, Twitter, Slashdot (they don’t offer SSL at present, but if they did…), etc.
Pretty much the only time I do care are for financial institutions. And guess what? They’ve already decided that SSL as used for identity verification is useless! Most of them (I can only think of one that I use that hasn’t) have already implemented a “security image” system wherein I pick a random image that gets shown to me every time I log in. If a site claiming to be the site I want shows me an image I don’t recognise, I’ll know that the site is a fraud. Is it perfect? Probably not. But it’s orders of magnitude better then what SSL error dialogs offer.
And I guess that’s really it: as much as I hate the phrase, I really think that the SSL error dialogs are “a solution in search of a problem.” In the cases where I care about site spoofing, the sites themselves have already implemented a better solution. In the cases where I don’t care, well… I don’t care.