Re: Comments & Documentation (was Re: semantics of init)
Re: Comments & Documentation (was Re: semantics of init)
- Subject: Re: Comments & Documentation (was Re: semantics of init)
- From: Jeff Harrell <email@hidden>
- Date: Fri, 6 Jun 2003 22:13:14 -0500
My commenting style tends toward the narrative. (This should come as no
surprise, as I am a writer by trade; programming is a consuming hobby.)
For example, here's a comment that I inserted when I made a change to
iTableView.h for use in one of my little toy projects:
// This class has been modified by yours truly (Jeff Harrell) to
support one teensy weensy
// additional feature. The message transposeEvenAndOddRows will toggle
the behavior of the
// class from odd-colored-rows to even-colored-rows. Why? Because I
used this class in a
// utility window that represented a queue of items being downloaded.
The queue was displayed
// in first-item-at-the-top order, so when the controller popped an
item off the queue, I
// wanted to be able to have the row tints shift upward along with the
items in the list. I
// implemented this by having the piece of code that pops the item off
the queue call
// transposeEvenAndOddRows. When the table redraws to reflect the new
queue, it draws with
// row colors that are the opposite of what they had been before. It's
nifty.
When I write in C, I find that I need to insert comments that explain
what the heck a block of code is trying to do. Generally I find that's
less necessary with Objective C, but I still write comments that try to
explain the high-level why and how, even though the what is (hopefully)
self-evident.
Here's another example of my commenting style:
// This seems pretty obvious, but that's easy for me to say because
I've been staring at it
// for the past hour and a half. It works like this:
//
// We store a pointer to the sort column. That pointer is initialized
to nil in awakeFromNib.
// When the user clicks on a column header, we check to see if the
column clicked matches the
// sort column. If it does, then we reverse the order of the list and
toggle the sort
// indicator. If it doesn't, then we sort based on the new column,
clear the sort indicator
// from the last column (if there was one), and post the ascending
indicator to the clicked
// column.
//
// Finally, we set the sort column pointer to the clicked column. Voila.
On Thursday, June 5, 2003, at 06:58 PM, Wade Tregaskis wrote:
Of course! I don't think anyone said "thou shalt always use
accessors everywhere". However, these situations are probably much
less frequent than you would expect (just like eXtremos like to point
out that comments are needed far less than most people think...)
This is probably especially true in Objective-C, where most of your
method names are suitably descriptive. In fact, I find the only
comments I ever put in my ObjC code are flags to indicate something's
broken or not implemented.
Does anyone else use comments in their ObjC code? I've been poking at
AutoDoc recently, and it seems to derive most (all?) it's results from
comments within the code. That's annoying for me, because I like my
code to be free of huge descriptive comment blocks, so I can actually
see what I'm doing when I'm working on it.
While I'm on the documentation side, what alternatives are there to
AutoDoc for generating HTML documentation? I like the Apple style, if
only because it's the 'standard', but the idea of having to fully edit
the AutoDoc-generated files kinda mutes most of the point of using
AutoDoc in the first place.
Wade Tregaskis
-- Sed quis custodiet ipsos custodes?
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.