Accessibility/Mac/ContributorGuide
Contents
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];