[ubuntu-us-in] Is Commenting Ideal? (was: Re: Time for a change)

Simón Ruiz simon.a.ruiz at gmail.com
Tue Nov 20 17:41:42 GMT 2007

On Nov 19, 2007 11:12 PM, David Ernst <david.ernst at davidernst.net> wrote:
> Actually, for the sake of conversation, I'll present that I've really
> become more of a believer in this ideal:
> "One might more accurately say that we think the code, properly
> crafted, is the best documentation."

That's a very good point.

> Still, this isn't a message about my own practices, this is a message
> about what the ideal should be.  What's undeniable is that people
> should produce source files that are easy to understand.  The question
> is, when are comments the best way to achieve that goal?  And, I must
> say, when I see code written nicely in a nice readable language (like
> Ruby or Python) I can even find the documentation annoying.  I want to
> emphasize, though, that most code is not written well enough to
> satisfy this request, and it's much better to document it than to just
> leave it confusing...
> Thoughts?

Ideally, yes. I completely agree that ideally code should be so clean
and legible as to make comments redundant..

However, I've yet to come up against a non-trivial project where I was
able to meet this ideal. Part of this, I'm sure, is that I'm only just
beginning, so I have a much lower threshold for "understandable" than
most experienced programmers.

I tend to write comments geared at beginners (or rather, myself as a
beginner), to help them (or rather, that I would have wanted to be
there to help me) figure the code out.

Also, since I'm only just beginning I'll often do something that I
know is ugly, because I don't yet know how to make it pretty. If I
already know I want to re-visit a piece of code at a later date, I
flag it with a comment.

Some examples:

* Well, so I was writing a Python script to get the system information
from the motherboard (serial number, manufacturer, product name,
etc.), and I started with someone else's code to just dump all of the
HAL information into a file. I hacked it (in the sense of using a very
large, unwieldy weapon) so that it only found the information I wanted
and returned it through a function. I literally would not know what
all that code was doing if I hadn't played with it for several hours
myself. DBUS stuff is just beyond my understanding, so I commented it
something like "# DBUS Black Magic(tm); returns the motherboard's
serial number".

* I'm writing a more-or-less proof-of-concept pack of scripts that I
eventually want to make database calls to get its information. For now
I'm hard-coding the information into the script and commenting "# It'd
be nice to get this info from a database at some point".

* I'm just starting to figure out how to use the CUPS module to set up
printers under Linux, and in order to set some options by default
(default media type to Letter and default duplexing to
2-sided-long-edge), I have to have a PPD object to modify before I
create the printer. HOWEVER, the only way I know how to get a PPD
object is to have a printer set up with the right PPD set to begin
with, so I have this really ugly hack (again, in the brutal, ugly
weapon swipe sense) that summons an un-set-up printer, tears out it's
PPD object, and sends the printer back to the void where it came from.
This is commented something like "# There's got to be a better way to
get the right cups.PPD object..."

* I've got a a main script that imports other scripts and runs them,
and I figure until the reader goes to read the other scripts, they
won't know what they're meant to return, so my main script goes a
little something like:

import UbuntuPrinters
if UbuntuPrinters.run(): # Returns true if printer setup was necessary
    os.system('/etc/init.d/cupsys restart')

So, I tend to write comments geared at either myself in the future as
I move towards a finished version and/or at beginners (or rather,
myself as a beginner), to help them figure my code out without having
to sit and read the whole thing.

This may change as I become a more proficient coder, but on the other
hand I like the idea of my code being accessible to people with a
"less than average" understanding of whatever language I'm working in.

> David


More information about the Ubuntu-us-in mailing list