平时生活和工作中的iOSiOS开发 oc中重要知识点优雅的iOS技术博客

Cocoa代码风格指南之命名规范（一）

2016-03-28  本文已影响1521人  xuyafei86

本文基于 Google 和 Apple 的代码风格指南中关于命名规范部分的总结。Apple 的指南基本都是命名规范，而 Google 的指南则的比较丰富。命名、风格、使用都有涉及，但讲的都是比较核心的规范。

注：本文只针对 Objective-C。如果是 Swift ，你还需要再看下官方文档的建议。

通用规则

insertObject:atIndex: // 正确
insert:at: // 错误

destinationSelection // 正确
destSel // 错误

- (int)tag // 在 UIView, UIControl 中都具有相同的功能
- (void)setStringValue:(NSString *) // 在许多 Cocoa classes 中都具有相同的功能

类

  1. 避免创建 public 实例变量。 [Google] [Apple] [General]
  2. 使用 @private，@protected 显式限定实例变量的访问权限。 [Google] [Apple]
  3. 确保实例变量名简明扼要地描述了它所代表的属性。 [Google] [Apple] [General]

协议 [Apple] [General]

NSLocking // 正确
NSLock // 错误

方法

- (id)viewWithTag:(int)aTag; // 正确
- (id)taggedView:(int)aTag; // 错误

- (void)invokeWithTarget:(id)target:
- (void)selectTabViewItem:(NSTableViewItem *)tableViewItem

- (CGSize)cellSize; // 正确
- (CGSize)getCellSize; // 错误

- (void)getLineDash:(float *)pattern count:(int *)count phase:(float *)phase; UIBezierPath

- (instancetype)initWithFrame:(NSRect)frameRect; // UIView
- (instancetype)initWithFrame:(CGRect)frame style:(UITableViewStyle)style; // UITableView, UIView 的子类

- (int)runModalForDirectory:(NSString *)path file:(NSString *)name types:(NSArray *)fileTypes;
- (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes;

- (BOOL) openFile:(NSString *)fullPath withApplication:(NSString *)appName andDeactivate:(BOOL)flag; NSWorkspace 

...action:(SEL)aSelector
...alignment:(int)mode
...atIndex:(int)index
...content:(NSRect)aRect
...doubleValue:(double)aDouble
...floatValue:(float)aFloat
...font:(NSFont *)fontObj
...frame:(NSRect)frameRect
...intValue:(int)anInt
...keyEquivalent:(NSString *)charCode
...length:(int)numBytes
...point:(NSPoint)aPoint
...stringValue:(NSString *)aString
...tag:(int)anInt
...target:(id)anObject
...title:(NSString *)aString

Delegate & DataSource [Apple] [General]

1.名称以标示发送消息的对象的类名开头，省略类名的前缀并小写类第一个字符。

- (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;
- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;

2.冒号紧跟在类名之后（随后的那个参数表示委派的对象）。该规则不适用于只有一个 sender 参数的方法。

- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;

3.上面的那条规则也不适用于响应通知的方法。在这种情况下，方法的唯一参数表示通知对象。

- (void)windowDidChangeScreen:(NSNotification *)notification;

4.用于通知委托对象操作即将发生或已经发生的方法名中要使用 did 或 will。

- (void)browserDidScroll:(NSBrowser *)sender;
- (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;

5.用于询问委托对象可否执行某操作的方法名中可使用 did 或 will，但最好使用 should。

- (BOOL)windowShouldClose:(id)sender;

C形式的函数 [Apple] [General]

  1. 它们有前缀，其前缀与你使用的类和常量的前缀相同。
  2. 大写前缀后紧跟的第一个单词首字符。
NSHighlightRect
NSDeallocateObject
  1. 查询第一个参数的属性的函数，省略动词。
unsigned int NSEventMaskFromType(NSEventType type)
float NSHeight(NSRect rect)
  1. 返回值为引用的方法，使用 get。
const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp)
  1. 返回布尔值的函数，名称使用判断动词 is/does 开头。
BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)

存取方法 [Apple] [General]

- (NSString *)title;
- (void)setTitle:(NSString *)title;

- (BOOL)isEditable;
- (void)setEditable:(BOOL)editable;

- (BOOL)showsAlpha;
- (void)setShowsAlpha:(BOOL)showsAlpha;

- (void)setAcceptsGlyphInfo:(BOOL)flag; // 正确
- (BOOL)acceptsGlyphInfo; // 正确
- (void)setGlyphInfoAccepted:(BOOL)flag; // 错误
- (BOOL)glyphInfoAccepted; // 错误

- (void)setCanHide:(BOOL)flag; // 正确
- (BOOL)canHide; // 正确
- (void)setShouldCloseDocument:(BOOL)flag; // 正确
- (void)shouldCloseDocument; // 正确
- (void)setDoseAcceptGlyphInfo:(BOOL)flag; // 错误
- (BOOL)doseAcceptGlyphInfo; // 错误

常量

1.使用枚举来定义一组相关的整数常量。 [Apple] [General]
2.枚举常量与其 typedef 命名遵守函数命名规则。如：来自 NSMatrix.h 中的例子：（本例中的 typedef tag（_NSMatrixMode）不是必须的） [Apple] [General]

typedef enum _NSMatrixMode {
    NSRadioModeMatrix           = 0,
    NSHighlightModeMatrix       = 1;
    NSListModeMatrix           = 2,
    NSTrackModeMatrix           = 3
} NSMatrixMode;

3.位掩码常量可以使用不具名枚举。如： [Apple] [General]

enum {
    NSBorderlessWindowMask         = 0,
    NSTitledWindowMask             = 1 << 0,
    NSClosableWindowMask           = 1 << 1,
    NSMiniaturizableWindowMask      = 1 << 2,
    NSResizableWindowMask          = 1 << 3
};

C++11 标准扩充了枚举的特性，可以指明用何种“底层数据类型”来保存枚举类型的变量。这样做的好处是可以向前声明枚举变量。Foundation 框架中定义了一些辅助宏来指定用于保存枚举值的底层数据类型。这些宏具备向后兼容能力，如果目标平台的编译器支持新的标准，就使用新语法，否则改用旧式语法。所以建议这样来使用。

typedef NS_ENUM(NSInteger, UIViewAnimationCurve) {
    UIViewAnimationCurveEaseInOut,         // slow at beginning and end
    UIViewAnimationCurveEaseIn,            // slow at beginning
    UIViewAnimationCurveEaseOut,           // slow at end
    UIViewAnimationCurveLinear
};
  1. 使用 const 来修饰浮点常量或彼此没有关联的整数常量。
  2. 枚举常量命名规则与函数命名规则相同。const 常量命名范例：
const float NSLightGray;
  1. 通常不使用 #define 来创建常量。如上面所述，整数常量请使用枚举，浮点数常量请使用 const。
  2. 使用大写字母来定义预处理编译宏。如：#ifdef DEBUG。
  3. 编译器定义的宏名首尾都有双下划线。如：__MACH__。
  4. 为 notification 名及 dictionary key 定义字符串常量，从而能够利用编译器的拼写检查，减少书写错误。Cocoa 框架提供了很多这样的范例：
APPKIT_EXTERN NSString *NSPrintCopies;

实际的字符串值在实现文件中赋予。（注意：APPKIT_EXTERN 宏等价于 Objective-C 中 extern）

数据集合 [Apple] [General]

- (void)addLayoutManager:(NSLayoutManager *)adObj;
- (void)removeLayoutManager:(NSLayoutManager *)anObj;
- (NSArray *)layoutManagers;
  1. 如果集合中的元素无序，返回 NSSet，而不是 NSArray。
  2. 如果将元素插入指定位置的功能很重要，则需具备如下方法：
- (void)insertElement:(elementType)anObj atIndex:(int)index;
- (void)removeElementAtIndex:(int)index;

1.以上集合类方法通常负责管理元素的所有者关系，在 add 或 insert 的实现代码里会 retain 元素，在 remove 的实现代码中会 release 元素。
2.当被插入的对象需要持有指向集合对象的指针时，通常使用 set... 来命名其设置该指针的方法，且不要 retain 集合对象。比如上面的 insertLayerManager:atIndex: 这种情形，NSLayoutManager 类使用如下方法：

- (void) setTextStorage:(NSTextStorage *)textStorage;
- (NSTextStorage *)textStorage;

3.通常你不会直接调用 setTextStorage:，而是覆写它。

- (void)addChildWindow:(NSWindow *)childWin ordered:(NSWindowOrderingMode)place;
- (void)removeChildWindow:(NSWindow *)childWin;
- (NSArray *)childWindows;
- (NSWindow *)parentWindow;
- (void)setParentWindow:(NSWindow *)window;

前缀

typedef NS_ENUM(NSInteger, UIViewAnimationCurve) {
    UIViewAnimationCurveEaseInOut,         // slow at beginning and end
    UIViewAnimationCurveEaseIn,            // slow at beginning
    UIViewAnimationCurveEaseOut,           // slow at end
    UIViewAnimationCurveLinear
};

头文件 [Google] [Apple] [General]

异常和通知 [Google] [Apple] [General]

[Prefix] + UniquePartOfName + Exception

UniquePartOfName 部分是有连续的首字符大写的单词组成。例如：

NSColorListIOException
NSColorListNotEditableException
NSDraggingException
NSFontUnavailableException
NSIllegalSelectorException

NSApplicationDidBecomeActiveNotification

通知由具有如下形式的全局 NSString 对象标识：

[相关联类的名称] + [Did 或 Will] + [UniquePartOfName] + Notification

例如：

NSApplicationDidBecomeActiveNotification
NSWindowDidMiniaturizeNotification
NSTextViewDidChangeSelectionNotification
NSColorPanelColorDidChangeNotification

附录 [Google] [Apple] [General]

  1. 标准 C 库中长期使用的缩写形式是可以接受的。如："alloc"，"getc"。
  2. 你可以在参数名中更自由地使用缩写。如：imageRep，col（column），obj，otherWin。
    alloc       Allocate
    msg         Message
    alt         Alternate
    nib         Interface Builder archive
    app         Application
    pboard      Pasteboard
    calc        Calculate
    rect        Rectangle
    dealloc     Deallocate
    Rep         Representation
    func        Function
    temp        Temporary
    horiz       Horizontal
    vert        Vertical
    info        Information
    init        Initialize
    max         Maximum
    
    ASCII，PDF，XML，HTML，URL，RTF，HTTP，TIFF
    JPG，GIF，LZW，ROM，RGB，CMYK，MIDI，FTP

博客：xuyafei.cn
简书：jianshu.com/users/2555924d8c6e
微博：weibo.com/xuyafei86
Github：github.com/xiaofei86

上一篇下一篇

猜你喜欢

热点阅读