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)

On 8/29/03 9:21 PM, Camillo Lugaresi didst favor us with:

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

Actually, that's a paraphrase of a line from a classic movie.
>
>> 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. 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? ;-)
>
> 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

> 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 wouldn't use something like that myself unless I had a pretty good reason
to, but I wouldn't rule out the possibility.
>
> 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 );

Sure, but this is a tiny amount of code. If it were larger and/or there were
some tedious detail I don't need to read through to get an overall picture
of the function containing this code were doing, I might put it in a
function. One of the reasons to factor stuff out into smaller, more narrowly
focused functions is so you don't get bogged down in details when trying to
read the function that calls those helper functions.
>
> 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. ;)

Well, that's my perspective. Like I said, the few comments I write are not
intended to be lessons in how to write Mac software. ;-)
>
>> 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 ;) */
>

get(&clue); // This was just an example

Larry
_______________________________________________
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: Camillo Lugaresi <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.