Re: Commenting style
Re: Commenting style
- Subject: Re: Commenting style
- From: Corbin Dunn <email@hidden>
- Date: Thu, 2 Mar 2006 12:42:25 -0800
On Mar 1, 2006, at 6:18 PM, Chad Armstrong wrote:
Over the years, we take on particular coding styles, which evolve
over the years and adapt to the tools and languages we use.
Especially with C-based languages, I feel fairly happy with how my
code looks. However, is there a particular style used in Cocoa/
Objective-C for creating comments, especially with function/method
headers?
Here is what we do in Cocoa.
-corbin
-----
Comments in header files.
Put them above the symbol(s) they document; don't hand-wrap, and use /
* ... */ style with the closing */ in the last line, by itself, in
order to provide separation between the comment and the declaration.
Note that this style is consistent with headerdoc. In addition, you
can use "//" comments on the same line as a declaration, for important
warnings or comments which would be interesting for developers to see
when they do "grep" or searches in Xcode.
/* This is a long comment which describes how borderColor: works.
Notice that it just wraps around and around and is not artificially
wrapped by the programmer so that it looks good no matter what width
of window you use.
*/
- (NSColor *)borderColor;
/* This is a long comment which describes how cString works. Notice
that it just wraps around and around and is not artificially wrapped
by the programmer so that it looks good no matter what width of window
you use.
You can have multiple paragraphs if you want. This is a second
paragraph. This style is consistent with headerdoc.
*/
- (const char *)cString; // Note: This method will raise exception if
the string cannot be converted.
enum {
NSAqua = 8, // The blue aqua variant
NSGraphite = 9 // The graphite aqua variant
};
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden