On Apr 15, 2008, at 10:25 AM, john darnell wrote:
4.) Comment verbosely and often. You may understand now what you are
doing and why, but six months from now, you won't. Don't fool
yourself
by saying "I'll add comments later," because, trust me, later never
comes.
I'm not going to argue with you because I think you've given some
pretty good advice here. I'm a fan of white space in my code as well,
and though there are some stylistic differences between us, I concur
with the basic concepts you laid out. I just thought a caveat might
be in order on #4 quoted above. And that caveat is simply "don't
overdo it". Comments are good and necessary, and should be done
contemporaneously with coding, on all that I agree completely. But it
can also be frustrating to have to deal with code like the following
hypothetical example (okay, this is may be a bit of an exaggeration,
but I've seen comments not that different from this out of young, well-
meaning programmers who take the "comment copiously" advice a bit too
seriously):
// This is a loop. It loops through the values in an NSArray
// called myArray. i is the loop variable, which we set
// to zero because arrays are zero-indexed in Obj-c
// we loop until i is less than [myArray count] because
// it is zero-indexed and going past the last item in the
// array will generate an exception. If I had used <=
// instead of < then we would have iterated past the
// last item in the array. I like puppies, but they can't code.
int i;
NSString *myString
for (i = 0; i < [myArray count]; i++)
{
myString = [myArray objectAtIndex:i];
NSLog(@"OMG, [EMAIL PROTECTED]", myString);
}
// Now that I've looped through my array using a for loop, I will
// ...etc. etc.
I think I would add to the end of your rule, " but don't waste time
writing comments to explain what should be obvious to any competent
programmer". Comments are to elucidate what shouldn't be clear.
Unless, of course your code is intended as a teaching tool. In most
cases, if your comment length exceeds your code length by a
significant amount, you might want to step back and ask yourself if
it's all necessary.
_______________________________________________
Cocoa-dev mailing list ([email protected])
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to [EMAIL PROTECTED]
