Accessibility/Mac/ContributorGuide

Mac Accessibility Contributor's Guide

In this document we will collect style guidelines and information useful for individuals looking to contribute to our Mac accessibility support. There is also an architecture and design page where one can find a technical overview.

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];