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)

[ Part 1 of 2: limit of 8 KB on message body, this one was just above 9 KB :) ]

At 22:02 -0400 29-08-2003, Laurence Harris wrote:
On 8/29/03 9:21 PM, Camillo Lugaresi didst favor us with:

> At 21:09 -0400 28-08-2003, Laurence Harris wrote:
>> For example, one could replace all this stuff we've been using in our
example with function named:

SizeControlToFillWindowLeavingSpaceForHorizScrollbar( control, window );

This would not only eliminate the need for a comment IMO, but it would
condense the code considerably in a good way by eliminating the clutter
created be the local variables.

Um, I think most readers would see this specific example as an
argument _against_ self-documenting code. It looks more like a
caricature than something I'd want to see in an actual program.

Well, I only came up with it to demonstrate that you *can* be pretty clear
if you want to be. But as for seeing something like this in an actual
program, I don't think that's relevant. If you named a function with that
name, you'd see it in a program.

I said "something I'd _want_ to see", not "something I'd see".

The point is that you don't have to be
limited to concatenating three words.

Do you think you'd ever see an API with a name like:

SetAutomaticControlDragTrackingEnabledForWindow()

in a program, or does that look like a caricature too? ;-)

The caricatural aspect of your function was that it had a ridiculously small and specific function, as if the author has an obsessive-compulsive drive towards factoring. :) (Not you: a fictional author who would actually put that code in a program. :P)
So specific that it's probably never going to be reused, and so small that it's easier to write directly the two lines that constitute its body, instead of calling the function. Think of an IncrementAccessCounterByThreeForTheSecondLastTask() function, if you're unconvinced. ;)

In contrast, the Carbon API you mentioned has a very reasonable purpose which is useful to many clients. It happens to have a long, descriptive name, but I have no problem with that - in fact, I think it's a good think.
It might seem strange that they didn't use a window property instead of a specialized call, but they probably didn't want to use a Window Manager API for a function specific to the Control Manager, so even that has an explanation.

> More specifically, I think that line of code is akin to the
tautologic comments lamented by many.
As was said before, you don't need to have comments that document the
OS, or teach what a pointer is, or explain that x = 1 "Sets the value
of x to 1".
Similarly, you don't have to factor every single step of an algorithm
into a separate function and give it a name that is basically a long
comment explaining what it does in plain English, save for the
absence of spaces.

Everyone is different, but I can read through code faster if it uses these
kinds of helper utilities and the names are meaningful. Maybe I'm inherently
skeptical, but if I see a comment preceding a line of code, I'll read the
comment, and then I'll read the code to be sure it matches up with the
comment. That may seem silly if you've never seen a comment that was out of
sync or a line of code that simply didn't do what the author thought it did,
but the compiler generates object code from source code, not comments, so I
want to be sure they match up. So anyway, I read comments *and* code, and if
I can eliminate the comment part, I can read through code more efficiently.
YMMV

Um, I'm not M. Uli Kusterer; I'm some other person who just recently joined this conversation. I never advocated the extensive use of comments.

I'll summarize the point I made in the excerpt you quoted above: excessive, pedantic self-documentation and factoring has the same problems as excessive commenting, and the fact that a useless comment is made into a C identifier does not make it any more useful. As I will show below, this also applies to the issue of synchronization.

[ End of part 1; read the exciting conclusion in part 2! ;) ]

Camillo
_______________________________________________
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.


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.