Coding Style Guidelines

[Joachim Bondo]

Thanks for providing the Coding Style Guide, Gus. In the hope that
this won't start a long discussion (we don't really need that), I have
two comments:

1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes. What I'm doing in my own projects is appending the
underscore, like in myInstanceVariable_.

2) Related to the above, for "private" methods, declared in .m's
@interface MyClass () block, I name the methods with a prefix to avoid
the same kind of possible name clashes, like LA_myPrivateMethod.

My recommendation is to incorporate these two points into The Official
Letters Coding Style Guide.

As a personal note, I've become quite fond of Google's Objective-C
Style Guide [0]. In particular, my code is never more than 100 chars
wide (Google recommends 80, but that's *too* old-school) which means I
can easily size and arrange my editor window and see all code without
having to scroll horizontally (which we all hate). As a consequence
I'm not aligning the colons in method calls which I thought would be a
problem at first, but with syntax-highlighting, this is not a
sacrifice in legibility. I also started using 2-space indentations as
per their guide.

My basic coding style is also greatly inspired by Apple's Coding
Guidelines for Cocoa [1], of course.

[0] http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml
[1] http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/index.html

Joachim
http://cocoastuff.com
@osteslag

[Caio Chassot]

Post by Joachim Bondo
Thanks for providing the Coding Style Guide, Gus. In the hope that
this won't start a long discussion (we don't really need that), I have

Uh… where is it?

[Joachim Bondo]

Post by Caio Chassot
Uh… where is it?

In the repository,
http://github.com/ccgus/letters/blob/master/resources/LettersCodingStyle.txt.

Joachim
http://cocoastuff.com
@osteslag

[Caio Chassot]

Post by Joachim Bondo

Post by Caio Chassot
Uh… where is it?

In the repository,
http://github.com/ccgus/letters/blob/master/resources/LettersCodingStyle.txt.

Ok, nice.

Some irregularities re spaces around =.

Line 94 is obviously missing one.

Lines 65,66: No spaces around = here?

[Gus Mueller]

Hola!

Post by Joachim Bondo
Thanks for providing the Coding Style Guide, Gus. In the hope that
this won't start a long discussion (we don't really need that), I have
1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes. What I'm doing in my own projects is appending the
underscore, like in myInstanceVariable_.

You don't happen to recall what session this was, do you? Up to now, I've only ever heard that methods prefixed with _'s were reserved for apple. The coding guidelines don't mention this with ivars.

I assume key value coding just works with ending an ivar with _?

Post by Joachim Bondo
2) Related to the above, for "private" methods, declared in .m's
@interface MyClass () block, I name the methods with a prefix to avoid
the same kind of possible name clashes, like LA_myPrivateMethod.

My only problem with this is it makes things a little bit funky to read. I suppose the idea behind this is to avoid unintentional overriding of methods in subclasses? The coding guidelines also mention doing this in subclasses as well. ugh.

Let me think about that. It's probably a good idea, but ick.

Post by Joachim Bondo
As a personal note, I've become quite fond of Google's Objective-C
Style Guide [0]. In particular, my code is never more than 100 chars
wide (Google recommends 80, but that's *too* old-school) which means I
can easily size and arrange my editor window and see all code without
having to scroll horizontally (which we all hate). As a consequence
I'm not aligning the colons in method calls which I thought would be a
problem at first, but with syntax-highlighting, this is not a
sacrifice in legibility. I also started using 2-space indentations as
per their guide.

I've always thought this problem was solved by turning on line wrapping. It's really not as bad as it sounds.

2-space indentions however, I just can't abide by. Things look too crazy crowded to my eyes!

Post by Joachim Bondo
My basic coding style is also greatly inspired by Apple's Coding
Guidelines for Cocoa [1], of course.
[0] http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml
[1] http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/index.html

oh hey, good link. I've added it to the guidelines.

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[Torsten Curdt]

Post by Joachim Bondo
1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes.

I also recall someone mentioning that.

You don't happen to recall what session this was, do you?  Up to now, I've only ever heard that methods prefixed with _'s were reserved for apple.  The coding guidelines don't mention this with ivars.

...and cannot remember which session it was either.

Just remember how it let to one of these discussions with some colleagues ;)

cheers
--
Torsten

[Martin Redington]

The "don't use initial underscores on instance vars" hint has been
around for a few years at least

e.g. http://cocoadevcentral.com/articles/000082.php

although I don't have an Apple reference for it, and some sample Apple
code uses leading underscores. In practice, I think a lot of people
either don't know about, or just ignore the advice.

I've seen mSomeInstanceVariable used as an alternative.

Post by Torsten Curdt

Post by Joachim Bondo
1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes.

I also recall someone mentioning that.

You don't happen to recall what session this was, do you?  Up to now, I've only ever heard that methods prefixed with _'s were reserved for apple.  The coding guidelines don't mention this with ivars.

...and cannot remember which session it was either.
Just remember how it let to one of these discussions with some colleagues ;)
cheers
--
Torsten
_______________________________________________
List help: http://lists.ranchero.com/listinfo.cgi/letters-dev-ranchero.com

[Gus Mueller]

Post by Martin Redington
The "don't use initial underscores on instance vars" hint has been
around for a few years at least
e.g. http://cocoadevcentral.com/articles/000082.php
although I don't have an Apple reference for it, and some sample Apple
code uses leading underscores. In practice, I think a lot of people
either don't know about, or just ignore the advice.
I've seen mSomeInstanceVariable used as an alternative.

Yea, I'd rather have this than postfixing it with a _. I want to know what relationship the variable has to the class before I finish reading it, (damn you apple! why can't you use something else?!)

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[Steven Huey]

Post by Martin Redington
The "don't use initial underscores on instance vars" hint has been
around for a few years at least
e.g. http://cocoadevcentral.com/articles/000082.php
although I don't have an Apple reference for it, and some sample Apple
code uses leading underscores. In practice, I think a lot of people
either don't know about, or just ignore the advice.
I've seen mSomeInstanceVariable used as an alternative.

There's a thread from a couple years ago from cocoa-dev about this:

http://www.cocoabuilder.com/archive/cocoa/203139-objective-instance-variable-names.html

Post by Martin Redington

While they append the phrase "especially in methods," they do mean
for everything, and you can collide with them if you name your own
identifiers (including instance variables) with leading underscores.

This issue came up several times while I was at Apple. The most recent
consensus (involving members of the Cocoa and compiler groups) was
that "_" prefixes for ivar names are mostly harmless, though they
should be avoided in method names. The reason is that ivar names are
less dynamic. If in the next OS release a system superclass of your
class adds an ivar with the same name, it's not a binary compatibility
problem (your class will continue to work, because its machine code
references the ivar as a numeric offset into the instance data, not by
name.) Whereas if a superclass adds a _method_ with the same name as
yours, all hell may break loose because your method will get called
instead.
Now, your code will break when you try to recompile it using the new
headers, because the compiler will complain about the ivar name
conflict. But then you just rename your ivar. It's a less serious
problem because it doesn't break any copies of the app that are out in
the field.

1. Leading underscores really will cause you to collide with Apple
and it really did blow up in my face.

Was it with a method or an ivar name?

3. XCode 3 now provides good color coding to distinguish ivars from
local vars.

I should try turning that specific color code on. I turned off all the
new Xcode 3 color coding because there were too many different colors
and it made the code look garish.

4. And besides, if you would use accessors properly, ivars should
very seldom show up in your code so you shouldn't have confusion
(this being the cause of #2 above).

I don't use accessors properly, then. ;) Method calls are so expensive
compared to ivar accesses that I don't use them for accessing instance
data, unless the accessor is nontrivial or the setter call is needed
to trigger KV notifications. (Also, I generally don't declare
properties for internal state that isn't part of the class's public
API.)
—Jens

[Gus Mueller]

Post by Steven Huey

Post by Martin Redington
The "don't use initial underscores on instance vars" hint has been
around for a few years at least
e.g. http://cocoadevcentral.com/articles/000082.php
although I don't have an Apple reference for it, and some sample Apple
code uses leading underscores. In practice, I think a lot of people
either don't know about, or just ignore the advice.
I've seen mSomeInstanceVariable used as an alternative.

http://www.cocoabuilder.com/archive/cocoa/203139-objective-instance-variable-names.html

Those are all good points. Talking with some folks offline, it seems that the _ivar problem is fixed by Xcode syntax highlighting, so maybe we should just do:

NSString *foo;

@property (retain) NSString *foo;
@synthesize foo;

Makes writing the synthesizers easier, matches up with the IB Outlets, and is obviously friendly with KVC. Jens mentioned that our ivars will only be messed up on a recompile, so that's good to know (and we'd get a warning from clang as well).

For private methods, I'd just like to keep doing what's currently done (no prefixes). Apple isn't going to be looking at our frameworks and saying "oh, we can't use that method name because it's public in this project…". They are just going to do what they want, and we'll have to cope regardless.

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[Rich Wardwell]

Post by Gus Mueller

Post by Steven Huey

Post by Martin Redington
The "don't use initial underscores on instance vars" hint has been
around for a few years at least
e.g. http://cocoadevcentral.com/articles/000082.php
although I don't have an Apple reference for it, and some sample Apple
code uses leading underscores. In practice, I think a lot of people
either don't know about, or just ignore the advice.
I've seen mSomeInstanceVariable used as an alternative.

http://www.cocoabuilder.com/archive/cocoa/203139-objective-instance-variable-names.html

NSString *foo;
@property (retain) NSString *foo;
@synthesize foo;
Makes writing the synthesizers easier, matches up with the IB Outlets, and is obviously friendly with KVC. Jens mentioned that our ivars will only be messed up on a recompile, so that's good to know (and we'd get a warning from clang as well).

+1 I think this makes the most sense.... not to mention, the underscores always make me think of systems Hungarian Notation.


Rich Wardwell
http://lifeisrich.org

[Steven Huey]

Post by Gus Mueller
NSString *foo;
@property (retain) NSString *foo;
@synthesize foo;

I haven't followed the project closely enough to know whether it's using the 64bit runtime or not, but if so, you can do without the first line, and the runtime will synthesize the ivar. It works for IBOutlets too, with something like:

@property (nonatomic, assign) IBOutlet NSButton* someButton;
@synthesize someButton;

[Jim Puls]

Post by Steven Huey
@property (nonatomic, assign) IBOutlet NSButton* someButton;
@synthesize someButton;

- Yes, it is using the 64-bit runtime
- I would endorse using synthesized instance variables, but that's another whole can-of-worms discussion about using direct variable access versus accessor/mutator methods within a class.

-> jp

[Gus Mueller]

Post by Jim Puls
- I would endorse using synthesized instance variables, but that's another whole can-of-worms discussion about using direct variable access versus accessor/mutator methods within a class.

I seem to be flailing quite a bit today. I didn't realize that this wasn't direct access.

This compiles for me with clang:

@interface LAObject : NSObject
@property (retain) NSString *foo;
@end

@implementation LAObject
@synthesize foo;

- (void) doFoo {
foo = @"";
}

@end

So even though I'm not doing self.foo, a method is being called when we assign foo to @""?

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[Jim Puls]

Post by Gus Mueller
@interface LAObject : NSObject
@property (retain) NSString *foo;
@end
@implementation LAObject
@synthesize foo;
- (void) doFoo {
}
@end

Quite the opposite. I was out of date; this was added recently and is the instance variable itself. I'm pretty sure this wouldn't compile under 10.5, and I missed this addition moving to 10.6.

-> jp

[Gus Mueller]

Post by Jim Puls
Quite the opposite. I was out of date; this was added recently and is the instance variable itself. I'm pretty sure this wouldn't compile under 10.5, and I missed this addition moving to 10.6.

Oh hey awesome.

Here's an updated version of the style guide:
http://gist.github.com/287306

Are there any violent objections to it?

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[August Joki]

How about the use of #param mark to break groups of method
implementations into conceptual chunks? protocols / notifications /
ibactions / etc.

-August

Post by Gus Mueller

Post by Jim Puls
Quite the opposite. I was out of date; this was added recently and is the instance variable itself. I'm pretty sure this wouldn't compile under 10.5, and I missed this addition moving to 10.6.

Oh hey awesome.
http://gist.github.com/287306
Are there any violent objections to it?
-gus
--
August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/
_______________________________________________
List help: http://lists.ranchero.com/listinfo.cgi/letters-dev-ranchero.com

[Jonathan Wight]

Post by August Joki
How about the use of #param mark to break groups of method
implementations into conceptual chunks? protocols / notifications /
ibactions / etc.

How about just writing code and worrying about the style-guide later.

No significant open source (1) project to my knowledge failed to ship because it was lacking a style guide.

Jon (Supreme style guide hater)

1: Make that _any_ project.

[Gus Mueller]

Post by Jonathan Wight

Post by August Joki
How about the use of #param mark to break groups of method
implementations into conceptual chunks? protocols / notifications /
ibactions / etc.

How about just writing code and worrying about the style-guide later.

Well, this came up because I got some code and saw that it wasn't how the rest was done, and thought "hey I better come up with some quick guide lines"

I'm ok with #pragma marks's, I don't use them myself (I just use the function popup + autocompelete to find what I need), but I see no reason not to use em.

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[Jonathan Wight]

Post by Gus Mueller

Post by Jim Puls
- I would endorse using synthesized instance variables, but that's another whole can-of-worms discussion about using direct variable access versus accessor/mutator methods within a class.

I seem to be flailing quite a bit today. I didn't realize that this wasn't direct access.
@interface LAObject : NSObject
@property (retain) NSString *foo;
@end
@implementation LAObject
@synthesize foo;
- (void) doFoo {
}
@end

No. The 64-bit runtime is synthesizing an ivar for you. You're still accessing the ivar directly here and need to do the right thing for retain/copy.

Ideally you should be doing self.foo = @""; It'll do the right thing for retain/copy and will allow subclasses to use their overridden setters.

Also sometimes - even in the new runtime you will still end up defining you own ivar. Esp. for things like lazy accessors.

Jon.

[Gus Mueller]

Post by Steven Huey

Post by Gus Mueller
NSString *foo;
@property (retain) NSString *foo;
@synthesize foo;

@property (nonatomic, assign) IBOutlet NSButton* someButton;
@synthesize someButton;

Yea- it's 64 bit only, so we can do this. It's pretty neat stuff. Might as well standardize on this too, since it's Apple's new shiny. As Brent says "Go to where the hockey puck will be, not where it is".

-gus

--

August 'Gus' Mueller
Flying Meat Inc.
http://flyingmeat.com/

[DINH Viêt Hoà]

Post by Gus Mueller
NSString *foo;
@property (retain) NSString *foo;
@synthesize foo;

I saw so much mistake with people using self.foo = something; or foo =
something;
using _foo = something or mFoo = something will be more explicit about
what you are trying to achieve.
I would not advise it since it's a common mistake.

[Martin Redington]

At the risk of dragging this thread out even further, the other
interesting google "standard" (which I personally have not followed,
althouh I'm considering it) is don't use .someProperty accessors,
prefer [someObject someProperty] instead, to avoid confusion with C
struct accesors.

Possible to get bitten by I guess, although I've never seen it in practice.

Post by DINH Viêt Hoà

Post by Gus Mueller
NSString *foo;
@property (retain) NSString *foo;
@synthesize foo;

I saw so much mistake with people using self.foo = something; or foo =
something;
using _foo = something or mFoo = something will be more explicit about
what you are trying to achieve.
I would not advise it since it's a common mistake.

Personally, (like dinh) I dislike this pattern (instance vars
unprefixed), as I tend to do

NSString *foo = [self foo];

// now use foo a bunch of times

which leads to ambiguity.

Post by DINH Viêt Hoà
--
DINH Viêt Hoà
_______________________________________________
List help: http://lists.ranchero.com/listinfo.cgi/letters-dev-ranchero.com

[Joachim Bondo]

Post by Joachim Bondo
1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes. What I'm doing in my own projects is appending the
underscore, like in myInstanceVariable_.

You don't happen to recall what session this was, do you?  Up to now, I've only ever heard that methods prefixed with _'s were reserved for apple.  The coding guidelines don't mention this with ivars.

I'll check when I'm back at my Personal PC Computer. It was a Matt
Drance session. It's his fault. It wasn't me.

I assume key value coding just works with ending an ivar with _?
2-space indentions however, I just can't abide by.  Things look too crazy crowded to my eyes!

I'm perfectly happy with your guidelines as is. I'm just say'n.

Joachim
Sent from my iPod shuffle
http://cocoastuff.com
@osteslag

[Joachim Bondo]

Post by Joachim Bondo
1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes. What I'm doing in my own projects is appending the
underscore, like in myInstanceVariable_.

You don't happen to recall what session this was, do you?  Up to now, I've only ever heard that methods prefixed with _'s were reserved for apple.  The coding guidelines don't mention this with ivars.

It was session 2009/125[0]: Effective iPhone App Architecture. It's
covered in the Compability section at 56:40 and onwards. The merssage
at around 58:06 is that the underscore prefix should be avoided for
*method names*.

While it's technically OK for ivars, it's discouraged.

[0]: https://deimos.apple.com/WebObjects/Core.woa/BrowsePrivately/adc.apple.com.2233735195.02233735201.2238219563?i=1319449089

Joachim
http://cocoastuff.com
@osteslag

[DINH Viêt Hoà]

Post by Joachim Bondo
Thanks for providing the Coding Style Guide, Gus. In the hope that
this won't start a long discussion (we don't really need that), I have
1) At WWDC 2009, Apple recommended *not* to prepend instance variables
with underscore, because that's used by Apple and could cause name
clashes. What I'm doing in my own projects is appending the
underscore, like in myInstanceVariable_.

should we care about that ?
prefixing with _ is handy and this just works :)