There are a few sections where we discussed motivations behind style choices in-person on our team and simply didn't explain, but there are also some that we cut when releasing publicly because they were too conversational in tone or not well-enough explained. The CGGemoetry functions section has a relevant quite that provides ample explanation for our reasoning, which that would serve us well in some other sections.

Dot notation, spacing, and some other sections are light on the reasoning even though we have considered each choice carefully. Some other sections are small stylistic choices that are pretty binary, but those need little explanation except preference.

These ones no longer work:

https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ObjectiveC/Introduction/introObjectiveC.html
https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html

Maybe there's a mirror somewhere.

While I'm not a zealot about convincing others to move away from using ! in conditionals, I wouldn't ever give up my use of == NO. Not only are inverted conditions typically harder to mentally process, using ! in fact often reduces visual clarity. Typically, this is the result of a lack of whitespace with something like if (![object boolValue]) { a critically important part of the condition is jumbled up with the delineation elements of the syntax. This gets worse as the complexity of your if condition increases (admittedly this is often a clarity problem in it's own rite). if (!([obj bool1] && ![obj bool2]) { -- quick, what is the expected result?

Truthfully, the primary reason I stopped using ! (after vehemently arguing with a co-worker that he was silly for suggesting I avoid it) is because I caused myself a world of hurt once. During what seemed like a straight forward refactor, I managed to accidentally remove a !, we didn't even catch it during code review -- it was just so easy to miss. This happened to be one of those insidious bugs that ultimately took hours to track down, and a fraction of a second to correct.

Don't like == NO? Fine, don't use it -- but don't punish the defensive coders that would like to, especially not with an empty statement like "increases visual clarity".

I generally follow this rule: In a category on a class you don't own, prefix the name of the category as you would a class (in caps) in both the file name and the actual name. Prefix that category's method names with that prefix in lowercase, followed by an underscore. For example UIFont+NYTAdditions.h, UIFont (NYTAdditions), + (UIFont *)nyt_titleFont.

The program will start

For example UIGestureRecognizerSubclass.h uses a category in a new file, However this breaks the private properties rule, since it is not extending a class:

Named categories (such as NYTPrivate or private) should never be used unless extending another class.

Is there a better way to expose protected methods?

Right now the guide simply says to use direct ivar access in dealloc. You should also directly access ivars in init* methods. More generally, you shouldn't really be invoking any method inside init* or dealloc methods. Other methods (including accessors that may be overridden) may expecting the object to be in a fully constructed state. When you're inside one of these methods, that is not the case.

http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Introduction/introObjectiveC.html

Would you use:
if(text.length){
// do something
}
or
if(text.length>0){
// do something
}
?

Just curious.

Account has been flagged

The style guide states that instance variables should always be accessed using self. if properties are being used. Apple recommends this as well but with an exception: except in initializer and dealloc methods.

This is due to the fact that during the time the object is being initialised (and, when applicable, dealloc'd), the object itself is considered to not be completely 'set up' with all of its properties publicly available for use and modification; the init and dealloc methods therefore respect this and as a result avoid any special behavior in the mutation and access of these properties that may assume a completely initialised state of the object.

I've seen this recommendation in a few places but I think the latest one in video form is at (and from) around the 6-minute mark of "Migrating to Modern Objective-C" from WWDC 2012.

Just thought I'd point this out as yet another geeky nitpick to a great style guide. :)

In your document a lot of variable names with the storage specifier static have prefixed names.

I understand the idea of prefixing for non-static consts, because during the linking phase the linker dies with obscure error messages. And if the names don't collide you still don't know which file is that topMargin coming from.

But what is the point of prefixing static variables? They can't be used outside of the file. The files shouldn't be long enough to need prefixing. It's easier and more clear to write topMargin instead of NYTBestViewControllerSidePanelTopMargin if we already have the NYTBestViewControllerSidePanelView.m opened.

Is there more rationale on this?

Do you have any automated style checker on your CI-server? I've searched for tools like that and the only thing I've found is https://github.com/Cue/ocstyle, but it has hard-coded rules in python language. And seems not to be developing any more. More tools could be found here, but the most of them are designed to apply convention to code, not to check the style.

Hi,

I'm pretty sure you're using pragma marks a lot.

I'm curious what's your best practise to structure code then.

Here's an example from us (@nxtbgthng):

We usually structure our implementation files like so like so (let's call this one Class.m):

/* copy right comment if necessary */

#import <Framework/Framework.h>

#import "OtherHeader.h"
#import "OtherHeaderInSemanticalGroup.h"

#import "NextHeader.h"

#import "Class.h" // we import the implementation files header last


// place for consts and defines if you can't avoid them


@interface Class () <SecretNotVisibleFromHeaderProtocol>
@property (readonly) NSString *text;
@end


@implementation Class

#pragma mark Class Methods

+ (void)load;
{
}

#pragma mark Lifecycle

- (id)init;
{
    ....
}

- (void)dealloc;
{
    ....
}


#pragma mark Accessors

@synthesize text = _text; // readonly properties don't come with an ivar by default
- (NSString *)text
{
    if (!_text) {
        _text = @"text";
    }
    return _text;
}


#pragma mark SecretNotVisibleFromHeaderProtocol

- (void)methodDefinedInTheProtocol;
{
}


#pragma mark UIResponder

- (void)methodOverridenFromUIResponder;
{
}


#pragma mark Private Helper

- (CGRect)rectFromStuff:(id)stuff;
{
}

@end


#pragma mark -
#pragma mark Stuff private to this class

// Put private implementation blocks and C functions here.
// They need to be declared on top of the file though and might make things a little more messy

So key points are:

• use pragma marks to group methods
• when subclassing or implementing a protocol group the methods that do so under the name of the super class or protocol
• always leave two empty lines above a pragma mark (we found them to be more visible that way)
• use a Lifecycle section to group all init and dealloc
• use a Class Methods section to group all static methods
• use a Accessors section to group all custom getters and setters
• keep @synthesize/@dynamic close to the getter/setter

Thanks for sharing your style guide. It's pretty close to how we do it which is a good sign for both of us ;)

-ullrich

With Rob Rix' statement in mind that the style guide should pay special attention to less experienced programmers, a naming convention that most of us follow but isn't documented is to end symbol names in the class or primitive type they represent.

This is especially important when dealing with a variable that is not precisely the semantic type it sounds like:

• NSString *URLstring = [self.item.URL.absoluteString stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
• NSURL *URL = [NSURL URLWithString:URLstring];
• NSString *apiReleaseDateString = [currentAPIDict valueForKey:@"date"];
• NSDate *apiReleaseDate = [DateFormatter dateFromString:apiReleaseDateString];

Is there a convention for using NSLog(), I find it useful to prefix logging with the class name (can even go further and add a prefix with the method).

Perhaps how NYTimes team handles NSNotification names.

Long time no see, What's up?

This:

if (!someObject){

should be probably this:

if (!someObject) {

• Possibly include info about nested blocks as well.

I would be happy if you'd enhance this doc to include some guidelines about switch-case control structures, especially the ones with {} blocks.

For quite some time I used to omit the nil comparison, as described here:
https://github.com/NYTimes/objective-c-style-guide#booleans

However it is easy to get too enthusiastic and slip a (nasty to track down) bug in like this:

@property (nonatomic, strong) MYSocket *socket;
- (BOOL)isSocketReady {
     return socket;
}

Instead of:

@property (nonatomic, strong) MYSocket *socket;
- (BOOL)isSocketReady {
     return socket != nil;
}

Saying that nil resolves to NO might give the wrong impression.
More correct would be: the if statement determines if the argument is not 0 and nil is defined as (id) 0, that's why it works.

More info on nil: http://nshipster.com/nil/
More info on BOOL: http://nshipster.com/bool/

If the property has an override setter, the dot-notation wouldn't return the same value as the setter.

Please take a look at the following list of missing documentation on

Executing Code After a Delay,
Concurrency,
Notifications

hello

setObject:(id)object forKey: was before, how do we do it now?

The Naming section advises

Properties should be camel-case with the leading word being lowercase.

When it makes sense for a symbol name to begin with a commonly used abbreviation, then the abbreviation should be capitalized according to common convention. In other words, the common naming convention takes precedence.

Examples appear scattered through Apple's class references:

• NSData *HTTPBody
• NSURL *URL
• const char *UTF8String
• [UIColor RedColor].CGColor

May I created README.md for Indonesian language?
I'll translate README.md into README_id-ID.

Thank you

If they aren't a good idea, the compiler will tell us.

Signed,
Former anti-dot.property zealot

If someone has already managed to tweak their uncrustify or clang to format as per this style. Adding it to the repo would be great help

Please share 👍

In the Booleans section the example reads:

if ([someObject boolValue] == NO)

But in Dot-Notation, it says "Dot-notation should always be used for accessing and mutating properties".

So shouldn't the example read:
if (someObject.boolValue == NO)

"Conditional bodies should always use braces even when a conditional body could be written without braces (i.e., it is one line only) braces should still be used. There are just too many little ways to get burned otherwise."

Please elaborate with at least one way to get burned that doesn't exist independently of bracing one-line conditional bodies. Otherwise, this is merely dogma and should at least be labeled "because we say so". Example: "...because then you might accidentally add a line after it that you expect to be part of the conditional." To which I'd say, "bullshit - the editor highlight this with its auto-indentation (because all code-aware editors I've used 'correctly' indent one-liners and not subsequent lines) and therefore this "problem" was solved long ago by a much higher and much-more-deeply-entrenched standard.

While I've never been a fan of the truly one-line if (someCondition) someExpression(); style because I prefer seeing an indentation to set off a body visually, I see nothing wrong with one-line bodies without braces after the test. In fact, it's more succinct and takes much less effort when scanning code with the eyes than all the visual weight of a braced body (the braces, of course, being there specifically because a way to group is needed).

So: my issue is mainly with the unbacked assertion that unbraced conditional bodies are somehow more dangerous than adding extraneous characters for a body that may never grow beyond that single line. It seems more like premature optimization and over-engineering to me.

I find it oddly disconcerting if class methods are interspersed with instance methods in interfaces and implementations

I assert that in the Apple frameworks, things like -count and -length should be read-only properties, and would be, were they written today (I'll accept "you're dead wrong" from Dave DeLong or other credible sources)

It seems that the compiler agrees with me, because it no longer warns about myArray.count as I am almost positive that it once did (I recall a warning against using "unintended side-effects" or something).

So someone explain to me why we shouldn't just use dot-notation getters for these "property-like" methods.

One counter argument might be: Who will decide which methods are "property-like"? To which I answer, I know them when I see them. They describe a property of an object (that's "property" without an @).

In most Core Data examples, I see people naming entities without a prefix. i.e. Person instead of ONCPerson. Which, of course, means that you end up with subclasses of NSManagedObject that have no prefix.

Is that standard practice?

i.e.:

if (![object trySomethingWithError:&error]) {
    …
}

not:

[object trySomethingWithError:&error];
if (error) {
    …
}

There are instances where the frameworks will write garbage into the parameter in passing cases, meaning that you can get false positives in the latter case; plus, any attempt to use the value will crash.

When unit testing a class it is often useful to expose its private properties.

@interface MyClass ()
@property (nonatomic) NSString * internalProperty;
@end

@implementation MyClass
 // ...
@end

How do you make myClass.internalProperty available in the test spec?

The way I see it there are 2 options

1. Duplicate the anonymous category at the top of the spec file (this is bad practice as you may change one anonymous category but forget to change the other).
2. Put the anonymous category in a file called MyClass_Private.h and include it in both MyClass.h and MyClassSpec.h. However this approach is forbidden in the rules.

Do you have any suggestions?

Does NYT have a specific style for where a bracket should appear after a method name in the .m file? For example, which one of these do you use?

A:

- (void)viewDidLoad
{
    [super viewDidLoad];
}

or B:

- (void)viewDidLoad {
    [super viewDidLoad];
}

I use A for methods, but use curly-brackets on the same line for any kind of structure within the method (conditionals, loops, etc).

The two examples for the ternary operator are not functionally equivalent

result = a > b ? x : y;

result = a > b ? x = c > d ? c : d : y;

Was hoping to add the following convention for boxed enums (described here). I figure trying to create a dictionary with enums would require the use of numberWithInt: or numberWithInteger:, so this would align with the current conventions.

typedef NS_ENUM(NSInteger, NYTDaysOfTheWeek){
     NYTMonday = 0, 
     NYTTuesday,
     NYTWednesday
};

NSDictionary * daysOfTheWeek = @{ @"monday" : @(NYTMonday), 
                                 @"tuesday" : @(NYTTuesday), 
                               @"wednesday" : @(NYTWednesday) };

"command + z" does not work after I writing "@s/"

本月要做的任务

• 完成图片
• 完成部署工具的设置
• 实现抽签功能
  fix#23

Dot notation obscures the exact nature of what you are doing with a property. It also provides a way to confuse structs with objects, which can lead to especially subtle and maddening bugs.

An example with NSView's Frame properties:

view.frame.size = blah; //does nothing.
view.frameSize = blah; //does something.

The Big Nerd Ranch (one of the foremost experts in OBJ-C, imho) has an excellent article about this very thing.

The QualityCoding blog also has a great article on why dot-notation is evil.

And to top it off, the excellent cocoa blog Cocoa Is My Girlfriend has a case against dot-notation.

edit: added links