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:09 -0400 28-08-2003, Laurence Harris wrote:
On 8/28/03 10:45 AM, M. Uli Kusterer didst favor us with:

At 10:23 Uhr -0400 28.08.2003, Laurence Harris wrote:
By this logic, programmers should be the best people to write user guides.
;-)

No! You're turning my words in my mouth.

As soon as I figure out what that means in English I'll come back with a
crushing reply. ;-)

Such an obvious metaphor shouldn't take you that long to figure out. ;)

Besides, weren't you advocating against useless comments? ;D

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.

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.
The pitfalls of excessive self-documentation are the same as those of excessive commenting. The only difference is that your text will be mostly blue instead of mostly red (or whatever color). :)

I think your earlier attempt was a better example of practical self-documenting code:

At 15:57 -0400 27-08-2003, Laurence Harris wrote:
const SInt16 windowWidth = intRight - intLeft,
windowHeight = intBottom - intTop,
kScrollbarWidth = 15;

SizeControl( control, windowWidth, windowHeight - kScrollbarWidth );

Of course it's not perfect, but if someone gets puzzled because you're using a couple of local variables, it's his job that should be changed, not your code. ;)

In fact, if you use enough of these kinds of functions the logic of your
code can become extremely easy to follow just from reading a sequence of
well-named functions:

CreateWidgetWindow( &widgetWindow );

CreateWidgetControlToDisplayContent( widgetWindow , &widgetControl );

SizeControlToFillWindowLeavingSpaceForHorizScrollbar( widgetControl,
widgetWindow );

CreateHorizontolScrollbarAtBottomOfWindow( widgetWindow, &scrollbar );

get(&clue); /* just use a NIB ;) */

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