iOS开发代码规范

2018/12/1 posted in  iOS

针对我的开发经验ViewController应该是这样的。

#pragma mark - Life Cycle|生命周期
#pragma mark - UITableViewDataSource and UITableViewDelegate|主要是一些代理的方法
#pragma mark - Private Method|私有方法(内部可调用)
#pragma mark - Public  Method|公有方法
#pragma mark - Set & Get|getter 和 setter方法
#pragma mark - Notification|接收通知之后执行的方法
#pragma mark - Event|一些视图的点击事件 比如button
#pragma mark - DelegeteHandler|代理的实现时间

1️⃣代码命名基础

①一般原则

  • 明晰

    • 尽可能保持清晰和简洁是件好事,但由于简洁,清晰度不应受到影响:

      比如insertObject:atIndex:比较清晰,而insert:at:却不知道发生了什么。

    • 一般来说,不要缩写事物的名称。把它们拼出来,即使它们很长:

      比如setBackgroundColor:setBkgdColor:
      有些缩写是很常见且取得了各方面的共识,所以你可以继续使用它们。可接受的缩写和缩略语

  • 一致性

    • 尝试在整个Cocoa编程接口中使用一致的名称。如果您不确定,请浏览当前头文件或参考文档以获取先例。
    • 当你有一个方法应该利用多态性的类时,一致性尤为重要。在不同类中执行相同操作的方法应具有相同的名称。

      code comment
      - (NSInteger)tag 定义中NSView,NSCell,NSControl。
      - (void)setStringValue:(NSString *) 定义在许多Cocoa类中。

②前缀

前缀是编程接口中名称的重要部分。它们区分了软件的功能区域。前缀可防止第三方开发人员定义的符号与Apple定义的符号(以及Apple自己的框架中的符号之间)发生冲突。

  • 前缀具有规定的格式。它由两个或三个大写字母组成,不使用下划线或“子前缀”。以下是一些示例:

  • 在命名类,协议,函数,常量和typedef结构时使用前缀。千要不能在命名方法时,使用前缀; 方法存在于由定义它们的类创建的名称空间中。另外,不要使用前缀来命名结构体的字段。

2️⃣命名方法

①通用规则

在命名方法时,请记住以下几条一般准则:

  • 使用小写字母开始名称,并将嵌入单词的第一个字母大写。不要使用前缀。
  • 对于表示对象采取的操作的方法,使用动词开始名称(禁止使用“do”或“does”)。
  • 如果方法返回接收者的属性,则在属性后面命名方法。除非间接返回一个或多个值,否则不必使用get

    code comment
    - (NSSize)cellSize; 正确
    - (NSSize)getCellSize; 错误
  • 在所有参数之前使用关键字

    code comment
    - (void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag; 正确
    - (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag; 错误
  • 在参数之前创建单词描述参数。

    code comment
    - (id)viewWithTag:(NSInteger)aTag; 正确
    - (id)taggedView:(int)aTag; 错误
  • 在创建比继承方法更具体的方法时,在现有方法的末尾添加新关键字。

    code comment
    - (id)initWithFrame:(CGRect)frameRect; 初始化方法
    - (id)initWithFrame:(CGRect)frameRect backgroundColor:(UIColor*)backgroundColor; 自定义初始化方法
  • 不要使用“and”来链接作为接收者属性的关键字。

    code comment
    - (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

②访问方法

访问器方法是设置和返回对象属性值的方法

  • 如果属性表示为名词,则格式为:

    - (type)noun;
    - (void)setNoun:(type)aNoun ;
    
  • 如果属性表示为形容词,则格式为:

    在声明属性的时候可以这么写
    @property(nonatomic,assign,getter=isAdjective)BOOL Adjective;

    - (BOOL)isAdjective;
    - (void)setAdjective:(BOOL)flag;
    
  • 如果属性表示为动词,则格式为:

    - (BOOL)verbObject;
    - (void)setVerbObject:(BOOL)flag;
    
  • 不要使用分词将动词转换为形容词:

    - (void)setAcceptsGlyphInfo:(BOOL)flag;
    - (BOOL)acceptsGlyphInfo;
    - (void)setGlyphInfoAccepted:(BOOL)flag;
    - (BOOL)glyphInfoAccepted;
  • 可以使用模态动词(动词前面加上“can”,“should”,“will”等)来澄清含义,但不要使用“do”或“does”。

    - (void)setCanHide:(BOOL)flag;
    - (BOOL)canHide;
    - (void)setShouldCloseDocument:(BOOL)flag;
    - (BOOL)shouldCloseDocument;
    - (void)setDoesAcceptGlyphInfo:(BOOL)flag;
    - (BOOL)doesAcceptGlyphInfo;
  • 仅对间接返回对象和值的方法使用“get”。并且当需要返回多个项目时,才应将此表单用于方法。

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

③代理方法

委托方法(或委托方法)是在某些事件发生时对象在其委托中调用的方法(如果委托实现它们)。它们具有独特的形式,同样适用于在对象的数据源中调用的方法:

  • 方法的开始使用通过标识发送消息的对象的类(类名省略前缀,第一个字母为小写):

    - (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;
    - (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
    
  • 冒号追加到类名前(参数是对委托对象的引用),并且该方法只有一个参数,即发送者。

    - (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;
    
  • 对此的一个例外是由于发布通知而调用的方法。在这种情况下,唯一的参数是通知对象。

    - (void)windowDidChangeScreen:(NSNotification *)notification;
    
  • 对于被调用以通知委托已发生或即将发生某些事情的方法,请使用“did”或“will”。

    - (void)browserDidScroll:(NSBrowser *)sender;
    - (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;
    
  • 虽然您可以使用“did”或“will”来调用要求委托代表另一个对象执行某些操作的方法,但首选“should”。

    - (BOOL)windowShouldClose:(id)sender;
    

④集合方法

对于管理对象集合的对象(每个对象称为该集合的元素),约定是具有以下形式的方法:

- (void)addElement:(elementType)anObj;

- (void)insertElement:(elementType)anObj atIndex:(int)index;

- (void)removeElement:(elementType)anObj atIndex:(int)index;

- (void)removeElement:(elementType)anObj;

- (NSArray *)elements;

有一点需要主要如果集合是真正无序的,那么返回NSSet而不是NSArray

⑤方法参数

有一些关于方法参数名称的一般规则:

  • 与方法一样,参数以小写字母开头,连续单词的第一个字母大写(例如,removeObject:(id)anObject)。
  • 不要在名称中使用“pointer”或“ptr”。使用参数的类型而不是它的名称声明它是否是指针。
  • 避免使用单字母和双字母名称作为参数。
  • 避免只保存几个字母的缩写。

常用的方法参数

...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

⑥私有方法

在大多数情况下,私有方法名称通常遵循与公共方法名称相同的规则。但是,常见的约定是为私有方法提供前缀,以便很容易将它们与公共方法区分开来。即使采用这种约定,私有方法的名称也可能导致一种特殊类型的问题。当您设计Cocoa框架类的子类时,您无法知道您的私有方法是否无意中覆盖了具有相同名称的私有框架方法。

Cocoa框架中大多数私有方法的名称都有一个下划线前缀(例如_fooData),以将它们标记为私有。从这个事实可以看出两个建议。

  • 不要使用下划线字符作为私有方法的前缀。
  • 如果您是一个大型Cocoa框架类(如NSView或UIView)的子类,并且您希望绝对确定您的私有方法的名称与超类中的名称不同,则可以将自己的前缀添加到私有方法中。前缀应尽可能唯一,可能基于您的公司或项目以及“XX_”形式。因此,如果您的项目名为Byte Flogger,则前缀可能是 BF_addObject:

虽然给私有方法名称加一个前缀的建议似乎与先前声称方法存在于其类的命名空间中的说法相矛盾,但这里的意图是不同的:防止无意覆盖超类私有方法。

3️⃣命名函数

Objective-C允许您通过函数和方法表达行为。当底层对象总是单例或者处理明显功能的子系统时,你应该使用函数而不是类方法。

函数有一些通用的命名规则,您应该遵循:

  • 函数名称与方法名称类似,但有几个例外:

    • 它们以您用于类和常量的相同前缀开头。
    • 前缀后面的单词的第一个字母是大写的。
  • 大多数函数名称以描述函数具有的效果的动词开头:

    NSHighlightRect
    NSDeallocateObject
    

查询属性的函数具有另一组命名规则:

  • 如果函数返回其第一个参数的属性,则省略动词。

    unsigned int NSEventMaskFromType(NSEventType type)
    float NSHeight(NSRect aRect)
    
  • 如果通过引用返回值,请使用“get”。

    const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp)
    
  • 如果返回的值是布尔值,则该函数应以变形动词开头。

    BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)
    

4️⃣命名属性和数据类型

①声明的属性和实例变量

一个属性声明有效地声明了访问器的属性方法,如果属性表示为名词或动词,则格式为:@property (…) type nounOrVerb;

@property (strong) NSString *title;
@property (assign) BOOL showsAlpha;

但是,如果声明的属性的名称表示为形容词,则属性名称将省略“is”前缀,但指定get访问器的常规名称,例如:

@property (assign, getter=isEditable) BOOL editable;

②常量

常量的规则根据常量的创建方式而有所不同。

2.1 枚举常量
  • 对具有整数值的相关常量组使用枚举。
  • 枚举常量和它们分组的typedef遵循函数的命名约定。以下示例来自NSMatrix.h:

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

    ⚠️注意,typedef标签是不必要的。

  • 可以用位掩码等内容创建未命名的枚举,例如:

    enum {
        NSBorderlessWindowMask      = 0,
    NSTitledWindowMask = 1 << 0,
    NSClosableWindowMask = 1 << 1,
    NSMiniaturizableWindowMask = 1 << 2,
    NSResizableWindowMask = 1 << 3
    };
2.2 用const创建的常量
  • const创建浮点值常量。如果常量与其他常量无关,则可以用来const创建整数常量; 否则,使用枚举。
  • const常量的格式由以下声明举例说明:

    const float NSLightGray;
    
2.3其他类型的常量
  • 通常,不要使用#define预处理器命令来创建常量。对于整数常量,使用枚举,对于浮点常量,使用const限定符,如上所述。
  • 对预处理器在确定是否将处理代码块时评估的符号使用大写字母。例如:#ifdef DEBUG

  • 请注意,编译器定义的宏具有前导和尾随双下划线字符。例如:__MACH__

  • 定义用于通知名称和字典键等用途的字符串的常量。通过使用字符串常量。如:APPKIT_EXTERN NSString * NSPrintCopies;

    #import <UIKit/UIKitDefines.h>
    UIKIT_EXTERN  NSString * NSPrintCopies;
    

③通知和异常

通知和例外的名称遵循类似的规则。但两者都有自己推荐的使用模式。

  • 通知

如果一个类有一个委托,那么它的大部分通知都可能由委托通过一个已定义的委托方法接收。这些通知的名称应反映相应的委托方法。例如,全局NSApplication对象的委托自动注册,以便applicationDidBecomeActive:在应用程序发布时接收消息NSApplicationDidBecomeActiveNotification。

通知由全局NSString对象标识,其名称以这种方式组成:
[关联类的名称] + [Did | will] + [UniquePartOfName] +通知
NSApplicationDidBecomeActiveNotification
NSWindowDidMiniaturizeNotification
NSTextViewDidChangeSelectionNotification
NSColorPanelColorDidChangeNotification

  • 异常

用来处理抛出的NSException使用异常。

异常由全局NSString对象标识,其名称以这种方式组成:

[Prefix] + [UniquePartOfName] + Exception
比如

NSColorListIOException
NSColorListNotEditableException
NSDraggingException
NSFontUnavailableException
NSIllegalSelectorException

5️⃣框架开发人员的技巧和技巧

开发框架有他们如何编写自己的代码比其他开发商更加谨慎。许多客户端应用程序可以在其框架中链接,并且由于这种广泛的暴露,框架中的任何缺陷可能会在整个系统中被放大。以下各项讨论了可以采用的编程技术,以确保框架的效率和完整性。

  • 类初始化

在调用类的任何其他方法之前,initialize 类方法为您提供了一个懒惰地执行一次代码的地方。

运行时发送initialize到继承链中的每个类,即使它没有实现它; 因此它可能initialize不止一次地调用一个类的方法(例如,如果一个子类没有实现它)。通常,您希望初始化代码只执行一次。确保这种情况发生的一种方法是使用dispatch_once():

+ (void)initialize {
    static dispatch_once_t onceToken = 0;
    dispatch_once(&onceToken, ^{
        // the initializing code
    }
}

⚠️注意: 因为运行时将initialize发送到每个类,所以可能initialize会在子类的上下文中调用 - 如果子类没有实现initialize,那么调用将落入超类。如果您特别需要在相关类的上下文中执行初始化,则可以执行以下检查而不是使用dispatch_once():

if(self == [NSFoo class]){
    //初始化代码
}
  • 指定的初始化器

指定的初始值设定init项是调用init超类方法的类的方法。(其他初始值设定项调用init类定义的方法。)每个公共类都应该有一个或多个指定的初始值设定项。

当您实现一个框架类时,您通常还必须实现其归档方法:initWithCoder:和encodeWithCoder:。注意不要在初始化代码路径中执行在取消归档对象时不会发生的事情。实现这一目标的一个好方法是,initWithCoder:如果您的类实现了归档,则从您指定的初始化程序和(它本身是指定的初始化程序)调用一个公共例程。

  • 初始化期间的错误检测

    • 通过调用重新分配自我super的指定初始化。
    • 检查返回值nil,这表示超类初始化中发生了一些错误。
    • 如果在初始化当前类时发生错误,请释放该对象并返回nil。

下面是🌰代码

- (id)init {
    self = [super init];  // Call a designated initializer here.
    if (self != nil) {
        // Initialize object  ...
        if (someError) {
            [self release];
            self = nil;
        }
    }
    return self;
}

参考

[1]Apple Guideline
[2]iOS Coding Style Guide 代码规范