开发命名规则

iPhone项目命名规则

撰写人：iPhone小组

撰写时间：2011-3-22

1.  命名

1.1 通用规则

1.1.1                不要声明以一个或多个下划线 ('_') 开头的名称

开头带有一个下划线（“_”）的名称通常由库函数（“_main”和“_exit”）使用。开头带有两个下划线（“__”)或一个下划线后接一个大写字母的名称保留给编译器内部使用。
名称还要避免下划线相邻，否则很难识别下划线的确切个数。

1.1.2                不要使用两个相连的下划线

1.1.3                避免使用只靠字母大小写才能区分的名称

只通过大小写才能区分的类型名称，它们间的差异是很难记忆的，也就很容易造成混淆。

1.1.4                避免使用缩写

应用领域中常用的缩写（如 FFT 指快速傅立叶变换），或在项目缩写清单中有定义的缩写，才能使用相应的缩写。否则，很有可能相似但不相同的缩写到处出现，之后就引进了混淆和错误（如将 trackIdentification 缩写成 trid、trck_id、tr_iden、tid、tr_ident等）。

1.1.5                选择清晰的、易辨认的、有意义的名称

从应用的角度选择名称，名词使用形容词修饰来提高局部（具体上下文）的含义。确保名称与其类型保持一致。
选择合适的名称，使以下结构：

objectName.FunctionName(...);

objectName->FunctionName(...);

[objectName FunctionName(...);

易于阅读并有实际含义。
不要使用短名称或缩写名称,也不要太长，以免编译截断名称。使用人们熟知的 E 作为自然对数的底数或 Pi 作为圆周率是例外。
示例:

原代码:

void SetForegroundColor(CColor fg)

读者直觉上会认为 fg 意指 foreground（前景）；但是，任何一个好的编程风格都不应留给读者作直觉推导的余地。

void SetForegroundColor(CColor foreground)

{

theForegroundColor = foreground;

}     

当使用参数 foreground（远离其声明）时，读者会认为 foreground 实际上就是指 foreground 的颜色。可以想象，它能代表任何一种可暗中转化为color的类型。 

推荐风格:

void SetColor(CColor newColor)

{

...

theColor = newColor;

...

}

对 newColor 进行了限定使它与其类型一致；因此增强了函数的语义。

1.1.6                使用名称的正确拼写

英语字符名称部分应正确的拼写，遵守项目要求的形式，如使用一致的英国英语或美国英语，但不能同时使用。这对注释也同样适用。

1.1.7                布尔值使用正值谓词从句

对布尔值类型的对象、函数及函数实参使用正值形式的判定句式，如FoundIt、IsAvailable，但不使用IsNotAvailable。

 

1.2 类与结构

1.2.1                名称使用名词或名词短语

使用简单形式的常用名词或名词短语，为类取名时要表达出它的抽象含义。基类使用更通用的名称，而对派生类使用更专用的名称。

typedef ... Reference; //出自标准库

typedef ... Pointer;   //出自标准库

typedef ... Iterator;  //出自标准库

struct tagPoint{....};

class CBankAccount {...};

class CSavingsAccount : public CBankAccount {...};

class CCheckingAccount : public CBankAccount {...};

1.2.2              类名

• Objective-C开发的类以大写字母“C”开头，其后每一个单词都以大写字母开头

       如：CGlobalLocation,CFont,CDialog

 

1.2.3              结构名

结构名加小写前缀"tag"，结构“}”之后其后每一个单词都以大写字母开头

例：

typedef struct tagPoint

{

    int nx;

    int ny;

} Point;

1.2.4              枚举名

枚举名前加小写字母“enu”，在“}”之后全部大写,单词之间以下划线“_”相连。

全部大写

例：

typedef enum enuKFILE_OPEN_MODE

{

    OPEN_READONLY  = 0,

    OPEN_READWRITE = 1,

    CREATE_ALWAY  = 3

} KFILE_OPEN_MODE;

 

1.2.5              前后缀

• 如果是派生类应在其类名中使用后缀来包含其基类信息,并且取名应能较准确描述该类的含义,否则不加后缀。

          如：CColorDlg,CEditView,COleServerDoc等。

• 当对象和类型的名称冲突或缺少合适的名称时，对象使用简单名称，类型名称添加后缀 mode、kind、code 等。
•  

1.3 变量

1.3.1              基本格式

变量名的命名遵从匈牙利记法。即：前缀 + 类型 + 变量名

 [m_|g_] type [class name|struct name] variable name

1.3.2              变量名使用混合大小写，并以小写字母开头。

         如：long  nTemp;  //normal
              long NTemp;  //abnormal

      LPCTSTR  lpszMenuName;

1.3.3              声明常量，宏，枚举常量

声明常量，宏，枚举常量时应全部使用大写字母，单词之间以单下划线相连。

            如：const   double       PAI=3.1415926;   //noraml
         const   double            Pai=3.1415926;   //abnoraml
        #define            PAI          3.1415926       //normal
            #define             Pai          3.1415926       //abnormal

  enum  Color{RED,BLUE,GREEN}; //normal
  enum  Color{red,blue,green};    //abnormal

1.3.4              变量名是用多个单词表示时

• 当使用混合大小写时，将修饰词放在前面，并且尽量拼写完整增加可读性。如：maxElement,currentFile 等。
• 当全部使用大写时，单词之间应用下划线连起来。如：BUFFER_SIZE,FILE_SIZE 等。

1.3.5              变量名命名应有意义

• 一律使用英文字母进行拼写；不用汉语拼音。

1.3.6              变量名大小在2~20个字母，避免单字母变量。

变量名大小应至少2~3个以上的字母，避免单字母变量。当变量单纯作为整型循环变量时，可以使用单个字母。如：i，j，k等。

                     例：chrName,hWnd等。

1.3.7              基本类型变量名中必须有其类型的修饰前缀。

1.3.8              子系统变量名前应加子系统小写名加“_”。

         如：icu_nNumber,dom_chrSelect.

1.3.9              系统全局变量名前应加前缀“g_”。

        如：g_nNumber,g_nSelect.

1.3.10          避免使用auto，register修饰词。

1.3.11          变量如果是指针变量,变量应加上字母p

      如：pMemDC,pGUIFactory,g_pCtrl 。

1.4 类与结构变量命名

对象变量命名除了具备普通变量的规则，还包括：

1.4.1              类成员变量名前加“m_”。

 如：m_bConnection,m_chrName 。

1.4.2              类静态成员变量名前加“ms_”。

如：ms_bConnection,ms_chrName 。

1.4.3              标准类/结构变量名要加上它的标准前缀或后缀；

                      如：dlgFileOpen,strName,mainWnd,memDC

如果类/结构没有缩写命名，不用加类/结构名前后缀。

                             如 localHttpProxy,domSomeObject,newPlan;

1.4.4              应该用一致的前(后)缀来命名。

应该用一致的前(后)缀来命名同一类对象(或指向对象的指针)，使人们容易识别对象(指针)的类型。

1.5 函数

1.5.1                过程类型的函数名称

• 所有函数名以尽量以动词开始，大写第一个字母，其后每个单词以大写开头，尽量采用组合词表示其功能
             如： CreateWindow,GetValue,FindNextObject
• Window系统的消息处理函数要求用加前缀On,如OnMouseMove()
• 对无返回值的函数(函数声明为 void 返回类型)或返回值使用指针或引用类型的函数,使用动词或动词短语。
• 对使用非 void 返回类型返回唯一一个值的函数,使用名词或名词短语。
• 对带有常用操作(行为模式)的类,使用项目选项列表中的操作名。例如:begin, end, insert, erase (标准库中的容器操作).
• 返回布尔值（谓词）的函数使用形容词（或过去分词）。谓词经常使用名词前添加前缀 is 或 has 的形式使名称表达一个肯定的声明。当对象、类型名或枚举型常量也使用简单名称时，这也同样非常有用。时态上要保持一致，力求准确。

示例

void Insert(...);

void Erase(...);

 

Name FirstName();

bool HasFirstName();

bool IsFound();

bool IsAvailable();

• 不要使用否定意义的名称，因为这会导致双重否定表达式出现（如 !isNotFound）；这使得代码更难以理解。有些情况下，通过使用反义词，如“IsInvalid”代替“IsNotValid”，可以使否定谓词变成肯定的而不需改变其语义。

示例

bool IsNotValid(...);

void FindClient(CName withTheName, bool& notFound);

Should be re-defined as:

bool IsValid(...);

void FindClient(CName withTheName, bool& found);

当需要使用同一通用含义时，使用函数的重载

当操作目的相同时，使用重载而不使用同义词；这尽量减少了系统中概念的数量和不同的操作，因此也就降低了整体的复杂性。
当重载操作符时，要确保操作符的语义保留了下来；如果不能保留约定俗成的操作符含义，则为函数选用另一个名称而不使用操作符重载方式。