Accessibility/Mac/ContributorGuide

Mac Accessibility Contributor's Guide

Code Style

Our code style is based on Google's Objective C Style Guide, with a few exceptions and additions. The Wikimedia style guide is also a good reference for things not covered here or in Google's guide.

Method Declarations

Objective C is very flexible in its handling of method declarations. These rules should help remove ambiguity.

Always Declare Methods

Objective C does not require instance methods to have a declaration in the @interface block. If a method is defined in the @implementation block, it is accessible to any caller that knows of its signature. All methods should be declared. If they are public, they should be in the @interface block in the header file. If they are private they should be in a private class extension in the mm file.

For example, a header file might look like this:

@interface Hello : NSObject
- (NSString*)world;
@end

The mm file will look like this:

@interface Hello()
- (NSNumber*)somethingElseThatIsPrivate;
@end


@implementation Hello
- (NSString*)world {
  return @"earth";
}

- (NSNumber*)somethingElseThatIsPrivate {
  return @(3);
}

// BAD! This method has not been declared
- (void)iAmNotDeclared:(NSString*)bah {
  NSLog(@"%@", bah);
}
@end

Mark Methods "final"

A class cannot declare a method as final and prevent subclasses from overriding it. If a method should not be overridden by a subclass put the word "final" in a comment above the declaration. For example:

// This method returns the word "bar"
// final
- (NSString*)foo;

Mark Methods "override"

A subclass does not need to declare an overridden method as such. If a method is overriding a method from a superclass, or is implementing a method from a conformed protocol, put the word "override" in a comment above the declaration. For example:

// This method returns the word "bear"
// override
- (NSString*)pooh;

NSObject Literals

Whenever possible, use @ literals when creating immutable objects. Be careful not to pass nil values into container objects as this will cause a crash.

// Do
NSArray* actions = @[@"AXPress", @"AXShowMenu", @"AXScrollToVisible"];
// Don't
NSArray* actions = [NSArray arrayWithObjects:@"AXPress", @"AXShowMenu", @"AXScrollToVisible", nil];

// Do
NSDictionary* keyValues = @{@"key1" : @"value1", @"key2" : @"value2"};
// Don't
NSDictionary* keyValues = [NSDictionary dictionaryWithObjectsAndKeys:@"key1", @"value1", @"key2", @"value2", nil];

// Do
NSNumber* isBest = @YES;
// Don't
NSNumber* isBest = [NSNumber numberWithBool:YES];

// Do
NSNumber* life = @42;
// Don't
NSNumber* life = [NSNumber numberWithInteger:42];