"Programs must be written for people to read, and only incidentally for machines to execute". -Abelson and Sussman
Programmers spend far more time reading code than writing it, and maintenance of any given code base dwarfs the effort needed to create it. With these things in mind, I have developed a coding style over the years that is intended to make code, above all, readable. Some of my style will always be controversial with some, but nothing is done without good reason. This page outlines my style, and why I do it that way. So If my coding style is infuriating you, (I hope it doesn't, but some people are remarkably religious about some of these things - including me!), then at least try to understand the why.
No really, it doesn't. The compiler doesn't care, it discards all spaces anyway, so there is NOTHING to be gained from cramming everything together as if density on the page somehow made the code faster. It doesn't. All it does is make the darn thing less readable to a human, and no more readable to the computer, so nobody is gaining. Therefore you'll see I space my code out for readability. I tend to group statements that relate to achieving a particular goal together, then add a blank line to separate it from the next mini-task, and so on.
The only argument I've ever seen for high density code that bears any scrutiny is that you can see more of it at a time. Perhaps, but if you need to spend twice as long figuring out what it's doing, what have you achieved? Give me a little extra scrolling any day. Also, as a practical measure, invest in a scrollwheel mouse and a bigger screen.
Oh, now this is one that is one of those pesky religious issues, and my view on this definitely seems to be in the minority. Most folk seem to prefer:
if ( somethingorother ) {
/* statements */
}
But I abhor this form. Once you have a few nested blocks, it takes effort to see where the blocks begin and end; which statements belong in which block. And it's hard to tell a block apart from a single line conditional. And a thousand other arguments that have been done to death. Fact is, I line my braces up, even if it costs- gasp!- a whole line! Get used to it, coz I ain't changing. The point is - lined up braces are more readable.
Since readable code is the goal, the habit of setting it out so it's pleasing to the eye is more than just being anal about tidiness - it has tangible benefits. That's why you won't find this in my code:
int somevariable=1;float power=2.5;
int anothervar;
NSMutableArray *stuff=nil;
Instead I feel it's worth making the variable names clear by separating them into columns. You'll see lots of columns in my code:
int somevariable = 1;
float power = 2.5;
int anothervar;
NSMutableArray* stuff = nil;
This makes it clear what the type is, what the identifier is, and that the assignments are not part of the name. And while I'm about it, I always left-associate the pointer operator:
NSString* myString;
NSArray* myArray;
This bugs some people, but it's perfectly logical - the variable type is a pointer to NSString, NSArray, etc. That's a distinct TYPE, so the pointer operator is PART OF THE TYPE, NOT PART OF THE NAME. Yeah but, you say, it makes it hard to make multiple assignments, such as:
NSArray *array1, *array2;
Well, don't do this! Put every variable on its own line in columns so that this "problem" never arises.
Another related thing that is a bit irritating to me is specific to Objective-C. Most Cocoa developers, including Apple's, seem to like to run the return type of a method hard up against the method name. Why? I don't know, it doesn't look nice and makes it less readable. My code separates them - often by quite a lot. So instead of:
-(int)whyOhWhyDoTheyDoThis:(float)irritationFactor withPrejudice:(int)max;
-(NSMutableArray*)mutableArrayWithAnnoyanceObjects:(NSDictionary *)grumble;
I separate the return type from the method like so:
- (int) thatsALotMoreReadable:(float) agreementAmount withFluffyBunnyRabbits:(BOOL) tehBunnies;
- (NSMutableArray*) mutableArrayOfBunnyRabbits:(NSDictionary*) burrow;
Thus it's clearer what the method name is, and what its return type is, at a mere glance. Combined with class methods lined up in columns, it makes browsing the headers for a class a lot more pleasurable. The above examples don't convey the real readability problems inherent in a class definition with hundreds of methods that don't bother to use whitespace wisely. You'll also notice that I add spaces where necessary to separate the various parts of the method for readability. When I am looking at the source for a class definition, I often have questions in my mind - what does this class do? What method do I need to use to do xyz? If I can quickly see what types are returned as a distinct entity from the names of the methods, I can answer these question much more quickly when confronted by an unfamiliar and (let's face it) a possibly undocumented class. Objective-C syntax is designed for readability with its parameter names, and so on, so why that benefit is then somewhat negated by lack of "punctuation" is a bit strange. That said, I do exactly the same with C++, so it's not that I'm singling out Objective-C for special treatment here. I just don't get why Apple's own Cocoa headers have to be so ugly.
Note that there are plenty of good resources about Cocoa style itself, all of which I agree with and stick to, where possible. Try these links for more on Cocoa specifically:
© 2006-2008 Graham Cox
