Volume Number: 21 (2005)
Issue Number: 7
Column Tag: Programming
by Aaron Hillegass, Chris Campbell, Marquis Logan
As developers and teachers, we spend a lot of time dealing with issues of style. Not just because we like to look cool for the ladies; code that is written by a stylish programmer is easier to read and maintain. The Cocoa community has developed idioms, and if you want other developers to be able to easily comprehend your code, you should follow those idioms.
Here is a perfect setter method that explicitly invokes key-value observing:
- (void)setBorderColor:(Color *)c
{
if (c == borderColor) {
return;
}
[self willChangeValueForKey:@"borderColor"];
[c retain];
[borderColor release];
borderColor = c;
[self didChangeValueForKey:@"borderColor"];
}
Notice the use of whitespace. In particular, we do not put spaces after colons. We do not put spaces after the type of the parameter (That is, "(Dog *)").
Also, notice that there are no comments. What this method does is self-evident from its name. Too many comments can be just as annoying as too few.
In an implementation file, methods should be grouped in a meaningful manner. In particular, we try to follow this order:
Class methods Initializers and dealloc copyWithZone: isEqual: hash initWithCoder: and encodeWithCoder: action methods other methods (subgroup meaningfully) delegate methods accessor methods (in setter/getter pairs)
Use #pragma mark to show where a group of methods begins. The information will show up in the popup in Xcode. For example, you might insert these lines:
#pragma mark Coding methods #pragma mark Color metrics #pragma mark Accessors
So that your Xcode popup would look like this:
Figure 1.
If you have a method that returns the brightness of a border, it should be named thusly:
- (float)borderBrightness;
We do not put articles on method names:
- (float)theBorderBrightness;
We do not prefix methods with get-:
- (float)getBorderBrightness;
The exception to this rule is if the method is pass-by-reference:
float r, g, b;
[borderColor getRed :&r
blue :&b
green :&g
alpha :NULL];
If a method takes one argument and is prefixed with set-, it should be an accessor. In particular, an action method should never be prefixed with set-.
The primary purpose of your .h file is so that I can create an instance of your class and send messages to it. Many people put too much information in their .h files. Don't declare any of the following in the .h file:
1) Delegate methods.
2) Private methods.
3) Any methods in a protocol that you conform to. For example, if you have:
@interface Chowder : NSObject <NSCopying>
There is no reason to declare copyWithZone: in your .h file.
4) Any inherited or overridden methods.
Declare temporary variable in a "just-in-time" manner. When I'm reading your code, I don't want to have to scroll to the beginning of the method to figure out the type of a local variable. Move the declaration as close to the first use as possible.
In a short column, it is easy to discuss small issues like code formatting and variable naming. For larger and deeper issues, we need a much bigger forum. At the ranch in August, we are hosting an "Analysis and Design Workshop." John Graziano, who had a major part in the design of Xcode, WebObjects Builder, and many of the animation systems at Pixar, will lecture and guide hands-on exercises that teach good design practices. He is going to focus on creating designs that make change and maintenance easy. John started developing these ideas at NeXT, and they have received much acclaim within NeXT, Apple, and Pixar. Bring your specifications, and go home with the beginnings of a really good design for your app. The workshop is August 15 - 19 in Atlanta. We hope to see you there.
Aaron Hillegass, Chris Campbell, Marquis Logan
