【翻譯】蘋果官網的命名規範之 Code Naming Basics-General Principles

蘋果官方原文連結：General Principles

程式碼命名基本原則：通用規範

 

程式碼含義清晰

儘可能將程式碼寫的簡潔並且明白是最好的，不過程式碼清晰度不應該因為過度的簡潔而受到影響。例如：

程式碼	解釋
insertObject:atIndex:	命名很好
insert:at:	不太清晰，什麼要被插入？at是指什麼？
removeObjectAtIndex:	命名很好
removeObject:	命名很好，因為他指明瞭（要移除）引數中的物件
remove:	不清晰，移除什麼？

 

 

 

 

 

 

 

 

 

通常情況下，不要用單詞的縮寫，即使單詞很長。否則程式碼會變得很難讀

程式碼	解釋
destinationSelection	命名很好
destSel	不太清晰.
setBackgroundColor:	命名很好.
setBkgdColor:	不太清晰.

 

 

 

 

 

 

 

你或許認為一些單詞的縮寫大家都明白，但是不一定。尤其當其他在不同環境下或者不同語言背景嚇的開發者看到你寫的方法或者函式名稱時。當然不排除有些單詞縮寫已經流行了很長時間並且很通用。你可以繼續使用它。

在介面命名中，避免歧義，像一些方法名稱可以被解釋為多種含義。例如

程式碼	解釋
sendPort	傳送一個埠 還是 返回一個傳送埠的名稱？
displayName	顯示一個姓名？還是返回一個使用者名稱稱？

 

 

 

 

 

一致性

在整個Cocoa 編碼介面中，儘量使用一致的命名。如果你不確定的話，看一看標頭檔案或者參考文件。

當你編寫了一個類中需要用到多型的時候，程式碼一致性顯得尤為重要。在不同的類中，命名相同的方法應該做同樣的事情。例如

程式碼	解釋
- (NSInteger)tag	在 NSView, NSCell, NSControl.中都有定義
- (void)setStringValue:(NSString *)	在一系列的Cocoa 類中均有定義

 

 

 

 

 

命名不要自我指示。例如 user.username 用 user.name 即可

程式碼	解釋
NSString	可以.
NSStringObject	NSString已經是物件型別，不必要的在加object

 

 

 

 

 

類和協議的命名

一個類的名稱應該包含一個能夠表明該類所要表達的意思或者功能。類名需要一個適當的字首。Foundation和Application框架已經有很多例子了，例如：NSString,NSDate,NSScanner,UIButton等

協議（Protocol）應該根據自身所包含的行為來命名

大多數協議都定義了相關聯的方法但是並不和一些特定的類有聯絡。這種協議命名不能和類命名混淆。一種通用的做法就是加 ing

NSLocking  （好的命名） NSLock（不像協議的命名，更像某個類的命名）

標頭檔案

定義相關的類或者協議。在一組相關的類，協議，分類等。把宣告放在一個檔案中，該檔案包含主類、類別或協議的名稱。

標頭檔案	定義
NSString.h	NSString 和NSMutableString 類.
NSLock.h	NSLocking 協議and NSLock, NSConditionLock, 和NSRecursiveLock 類.

 

 

 

 

 

包含框架標頭檔案。每一個框架都應該有一個標頭檔案，並且標頭檔案命名和框架命名一致，標頭檔案中包含框架中所有的公開標頭檔案。例如：Foundation.h （Foundation框架），AFNetworking.h

備註：

ambiguity  歧義

interpret 解釋