search

kodecocodes / objective-c-style-guide

A style guide that outlines the coding conventions for Kodeco
http://www.raywenderlich.com/62570/objective-c-style-guide
3.1k stars 625 forks source link

Symbol prefix: 2 vs. 3 characters #38

Closed sberrevoets closed 10 years ago

sberrevoets commented 10 years ago

The Cocoa Guidelines are ambiguous when it comes to symbol prefixes. For example, the Coding Guidelines for Cocoa say (emphasis mine):

A prefix has a prescribed format. It consists of two or three uppercase letters and does not use underscores or “sub prefixes.”

However, the Programming with Objective-C: Conventions page states

Your own classes should use three letter prefixes. These might relate to a combination of your company name and your app name, or even a specific component within your app. As an example, if your company were called Whispering Oak, and you were developing a game called Zebra Surprise, you might choose WZS or WOZ as your class prefix.

What are your thoughts on this? I know the guide says to use RW, but since the three-letter prefix appears to be preferred, that wouldn't follow the convention. I know it's nitpicky, but that's what we're here for, right? :]

cbess commented 10 years ago

I think it makes sense to prefer three letter prefixes. As Apple basically has freedom to use any two letter prefix they need. I don't know of any three letter class prefix for an Apple class (Mac or iOS). I was actually pondering this not to long ago. Having worked with Apple SDKs since 2005, I believe you will future proof your class names if you choose three letters for a prefix. Just my thoughts.

funkyboy commented 10 years ago

I agree on the three letters, it's safer. If we had to pick one with three letters I propose RWV, the V in honour of Mrs Wenderlich :)

icanzilb commented 10 years ago

I don't see any benefit to using 3 character prefix. It feels like extra typing for little effect. Just about every open source lib out there uses 2 characters prefix and I feel that's good enough.

ColinEberhardt commented 10 years ago

Just about every open source lib out there uses 2 characters prefix and I feel that's good enough.

That is quite true, the majority do - however they are all putting themselves at risk of colliding with a future Apple class name. It's a pretty small risk, but it does exist.

However … putting this is context, we are writing a code style purely for the Ray Wenderlich site. These are not long-lived open source projects, they are little apps. I'd be happy to use a RW prefix, and if, in the highly unlikely event, it does collide in the future, we can change it.

tdahbura commented 10 years ago

Unless apple decides to release a new API and pounce on the two letters. I think we would be safer with three, it is extra typing but less than having to go back later.

Tony

Sent from my iPhone

On Jan 15, 2014, at 8:38 AM, Marin Todorov notifications@github.com wrote:

I don't see any benefit to using 3 character prefix. It feels like extra typing for little effect. Just about every open source lib out there uses 2 characters prefix and I feel that's good enough.

— Reply to this email directly or view it on GitHub.

sberrevoets commented 10 years ago

@tdahbura: That's my main issue with a two-letter prefix too. Everything could be fine now, but if they release a new framework with two-letter prefix, the chance of a collision becomes pretty significant. Even if the actual class names are different, it's probably a bad idea to use the same prefix that Apple uses in their frameworks.

icanzilb commented 10 years ago

Guys ... this style guide is not a style guide for ObjC for reusable classes. Please note that! It's a guide style aimed at online tutorials/ our books. If the case was this style was aimed at creating reusable classes I could see a benefit in making 100% of not clashing with Apple's namespaces, but since it's not - there isn't any such benefit.

cbess commented 10 years ago

I read the links above and found this as well: Programming with Objective-C: Customizing Existing Classes. They are strongly suggesting using three letters. @icanzilb I see your point, but I consider Apple an authority on Obj-C, since they basically own/dictate it's use. If you are teaching/educating someone on how to name classes, they should use Apple's suggested conventions. Per Apple, it is a best practice. Is it worth it to go against Apple just to save one/two capital letters?

moayes commented 10 years ago

+1 @icanzilb. I see the benefit of a 3-letter prefix, but given the scope and purpose of this guide I think it is not an issue.

icanzilb commented 10 years ago

@cbess I'm always for teaching things that people would use. Teaching people something they'll discard themselves is of no good for anybody. For example - Apple telling people to use 3char prefixes - check how many people do that.

sberrevoets commented 10 years ago

@icanzilb True, but in my opinion that doesn't justify teaching it the non-preferred way.

icanzilb commented 10 years ago

everybody on the Internet is entitled to one aren't they :+1:

cbess commented 10 years ago

@icanzilb Appealing to majority doesn't really justify "accuracy or correctness", because everyone could be wrong. Hence, having an authority. And since Apple has given thier two cents on the subject I think it is best to honor/heed their advice. You assume folks will discard it. This probably happens because they think it is arbitrary, not suggested by Apple. And maybe you (this guide) can help people know the "best" way to code.

ColinEberhardt commented 10 years ago

I've heard that iOS 8 is coming with a new Reality Warping framework.

cbess commented 10 years ago

@ColinEberhardt Haha, it might! And it'll be magical (probably).

ndubbs commented 10 years ago

@raywenderlich proposed the RW prefix, so I'm interested to see what his thoughts are on what a three letter prefix should consist of.

cwagdev commented 10 years ago

I prefer and use 3 in my projects.

cwagdev commented 10 years ago

@ColinEberhardt are you sure it's not Reality Distortion?

rwenderlich commented 10 years ago

@cbess I totally understand your point and think agree would make sense for open source projects and areas where you really wanted to make sure your code would last a long time without changing. But the fact of the matter is for our sites/books and the rapid release cycle of iOS, they're most likely out of date within a year anyway and doubtful if the code even runs without warnings :P

I think it would be best to stay with RW, as it's really the prefix that makes the best sense for our site - and in the unlikely event it gets snagged by Apple, we'll change it. Maybe we could put a little note somewhere that says "for your own projects, consider using a 3-char prefix".

cbess commented 10 years ago

@rwenderlich Understood. If its a point of convenience, then by all means use two (RW), but if correctness is the aim, then three letters (RAY) would be more considerate of Apple's best practices. And I think the note should use the same language as Apple, which is along the lines of "prefers", "insists", "commands", etc :) If it matters or helps anyone else, our teams (at Bottle Rocket Apps) have started changing our class prefixes from BR to BRA.

tdahbura commented 10 years ago

My one additional point on this is we are viewed by the readers of our stuff as best practices folks. Even in our tutorials we strive to teach "the right" way. Nothing is worse in my opinion than reading tutorials or books where the author's code would not stand up to a code review scrutiny. How many Java books out there that show System.exit() calls in exception handlers for web services modules?

Apple has indicated they reserve two letters...we can always put footnotes on it but the "correct" or Apple way is not to use two letters.

My projects have switched to three letters awhile ago.

I prefer our style guide to be what we do versus do what I say not what I do.

Just two more cents...

You guys should see the curly brace argument on one of my projects!

Sent from my iPad

On Jan 15, 2014, at 6:52 PM, "C. Bess" notifications@github.com wrote:

@rwenderlich Understood. If its a point of convenience, then by all means use two (RW), but if correctness is the aim, then three letters (RAY) would be more considerate of Apple's best practices. And I think the note should use the same language as Apple, which is along the lines of "prefers", "insists", "commands", etc :) If it matters or helps anyone else, our teams (at Bottle Rocket Apps) have started changing our class prefixes from BR to BRA.

— Reply to this email directly or view it on GitHub.

rwenderlich commented 10 years ago

Hm... good point Tony, I suppose I could be convinced on this. If we were to use a 3-letter prefix, what would it be though? Here are a few ideas:

RWC for raywenderlich.com RWT for raywenderlich.com team/tutorial RAY not a huge fan of that one, but possibly RTT for raywenderlich.com tutorial team

sberrevoets commented 10 years ago

I'd vote for RWT, where the T stands for Team. RWC is fine, too, but since a lot of people refer to the website simply by your initials, I think it's important to have RW in there.

cbess commented 10 years ago

+1 @tdahbura. I agree with @Scott90. @rwenderlich, I'm not a big fan of RAY either, I think RWT is most fitting.

ndubbs commented 10 years ago

I will update the style guide to use three letters (RWT).

tdahbura commented 10 years ago

I like RWT.

Sent from my iPad

On Jan 15, 2014, at 9:26 PM, rwenderlich notifications@github.com wrote:

Hm... good point Tony, I suppose I could be convinced on this. If we were to use a 3-letter prefix, what would it be though? Here are a few ideas:

RWC for raywenderlich.com RWT for raywenderlich.com team/tutorial RAY not a huge fan of that one, but possibly RTT for raywenderlich.com tutorial team

— Reply to this email directly or view it on GitHub.