Mailing Lists: Apple Mailing Lists
Image of Mac OS face in stamp
 
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [OT] Commenting source code (was Re: Problems with Controls Manager)

At 21:57 Uhr -0400 27.08.2003, Laurence Harris wrote:
Okay, I'm open to hearing the various interpretations of what "windowWidth"
could mean, and frankly, I whipped this out in a rush. If I were actually
doing this in code I'd probably use portWidth or portRectWidth instead of
windowWidth.

The problem is that "windowWidth" could be interpreted as "width for the window", or "width of the window", which means you could be completely on the wrong track.

In theory comments are great. In practice they can vary widely from useless
restatements of an API name and long rambling dissertations which clarify
little or nothing to genuinely useful comments. So the first challenge is
learning how to write *good* comments. (lots of good and true stuff snipped)

That's all true. However, it's true for writing self-documenting code just as much. Incomprehensible is incomprehensible, whether it's in a comment or in source code. And considering that, writing self-documenting code is actually *harder*, because not only do you have to come up with a description that exactly says what's going on here, you also have to fit that description into C's tight set of rules of what a valid identifier is.

I think you can write self-documenting coding for just about anything if you
are skilled enough at it. And make no mistake, it takes a skill you have to
learn.

True. But as I said, I found that writing good comments means being able to express yourself clearly in English (or German, or whatever language you're using). Writing good self-documenting code requires that even more, with an even better grasp of the language. So, by commenting heavily, you first learn the basic skills. Then, once you're good at that, you can move on to trying to make your comments shorter. And once you've done that, you can finally take the final leap and try to write code that suffices as the comment.

But so far, none of the examples provided has convinced me that self-documenting code really works. I've found flaws in any of them, which a quick comment would have solved.

// Make the list control the size of the window (leaving room for scroll bar):

Some of you may agree that the code pretty much says what it does. But just to be sure, I'd put a comment there, that doesn't use the exact same words as the code. This redundancy has the advantage of giving the reader a second opportunity to understand what's going on.

And for those who are in a hurry, it would remain comprehensible even if I'd hurried and written one-character variable names. Yes, I have to keep them updated. But then, somebody who changes the code could simply put a one-char variable somewhere in there, and the self-documenting code wouldn't be.

> MyFile.comments would be useless.

To you, maybe. To me, definitely. To someone else? Who's to say?

Either write *real* separate
(programmer) documentation (which we all *should* be doing, but few
of us really do these days),

Because we're all lazy bums like you said!!! LOL

True ;-) But what I meant is: A .comments file would be just as maintainable as any other kind of external documentation. The advantage of comments is exactly that they are *in the code* exactly "where the rubber hits the road", as my Software Engineering prof used to say.

I *never* made some of the mistakes I saw in the code I described. ;-) And
the worst part was that this code was written by my boss, who had his Ph.D.
in AI. How do you tell your boss his code sucks? LOL Actually, there *is* a
way: You turn in your resignation and tell him you'd rather be unemployed
than have to work with that code again.

Reminds me of that guy who did a great fix to some MS program ... was it DOS? Anyway, it was back when they were still rather small, so he went over to Gates and showed him how he'd turned this crappy code into great code... only to find out that this bit of code had been written by Gates himself.

> Well, the OP *did* say most of these comments were done for that
exact purpose. If I understood correctly, this is his first Mac app.

Right, but my comment was intended to be more general than that.

Sure, for any other application these comments would have been less than useful.
--
Cheers,
M. Uli Kusterer
------------------------------------------------------------
"The Witnesses of TeachText are everywhere..."
http://www.zathras.de
_______________________________________________
carbon-development mailing list | email@hidden
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/carbon-development
Do not post admin requests to the list. They will be ignored.
References: 
 >Re: [OT] Commenting source code (was Re: Problems with Controls Manager) (From: Laurence Harris <email@hidden>)



Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Contact Apple | Terms of Use | Privacy Policy

Copyright © 2007 Apple Inc. All rights reserved.