" width="21" height="15" align="absmiddle">

程序风格的要素－C++风格指南

原著：Neill Kipp
翻译：Panic
2005年3月30日

译者序：这是一篇写于1996年1月23日的文章，到现在已经有9个年头了，很陈旧，有可能跟不上形势，但是有些东西仍然值得现在的开发者学习，我翻译这篇文字仅供读者参考。

原文链接：http://{域名已经过期}/reference/articles/article708.asp

文件
　　头文件有".h"后缀。头文件包含类(class)，结构(struct)，和联合(union)的声明，枚举(enum)的声明，#define，typedef。
　　实现文件有一个".cc" (UNIX) 或者".cpp" (Windows, DOS)后缀。实现文件包括函数和方法的实现。
　　在头文件和源代码文件中安排一个页眉。页眉可以包含标题，作者，日期，和一些工程的信息，比如这个文件是配合整个工程的。

一些名字

通用C++字符的名字：
（注：这些都是符号的英文原名，目前并没有完全标准化的汉语词汇对应，所以后面的翻译只是个人建议）
{ open brace, open curly 左花括号 } close brace, close curly 右花括号 ( open parenthesis, open paren 左圆括号 ) close parenthesis, close paren 右圆括号 [ open bracket 左方括号 ] close bracket 右方括号 . period, dot 句号，点 ! exclamation point, bang, not 叹号，否 | bar, vertical-bar, or, or-bar (actually a "vertical virgule") 竖线，按位或 & ampersand, and, reference, ref 和，按位与，引用，取地址 * asterisk, multiply, star, pointer 星号，乘号，星，指针 / slash, divide 斜线，除号 // slash-slash, comment 双斜线，注释符 # pound 井号 （宏：#，参考 把符号转化为字符串的宏技巧 ） \ backslash, (sometimes "escape") 反斜线，（有时候做转义符）（还有一个：续行符） ~ tilde 按位取反
基本类型 "char" 通常发音是"charcoal."的首音节。有时念作 "care" 或者 "car."

名字和排版

命名约定的名字

• interspersed_underscores 中间下划线
• lowercaseMixedCapital 小写混合（首字母）大写；
• CapitalMixedCapital （首字母）大写混合（首字母）大写；
• ALL_UPPERCASE 全部大写

命名约定的应用

• enumeration_item_name 枚举，小写加下划线；
• variableName 变量，小写前缀加首字母大写后缀；
• TypeName, ClassName, MethodName() 类型名，类名，方法名，首字母大写前后缀；
• {域名已经过期} Unix/Linux文件名：每个单词首字母大写；
• dosfn.cpp windows/dos文件名：全部小写；
• POUND_DEFINES 宏定义，全部大写；

自成档代码（也就是没有文档，仅靠注释和代码说明的源代码文件）

• 程序中为每个名字使用完整拼写.

避免直接使用数字(Magic number)

• 不允许出现除了0（有时也包括1）之外的数字常量. 使用常变量或者宏定义（#defines）.

空白

• 空格(按空格键得到) ；
• 新行(按回车键得到) ；
• 制表符(tab) (用8个空格代替) ；

空白和排版

• 左花括号之后, 每行缩进4个空格直到对应的右花括号出现.；
• 如果if, while, 或 for 后面没有跟花括号, 下一行缩进两个空格；
• 冒号结尾的语句，反向缩进两个空格(public, case)；
• 保留字(if, else, class, struct) 前后要加1个空格除非已经因为新行或者特殊标点做了缩进；
• 运算符和比较符前后要有一个空格 (除了!之外)；
• 指针变量 (&,*) 声明的时候要前后加一个空格；
• 指针变量 (&,*) 在表达式中，前面（不是后面）要加一个空格llowed) ；
• 左圆括号后要加一个空格；

换行

• 在下面这些关键字后的左花括号后要换行: class, struct, union, enum, method, function (而不是: if, else, do, for, while, switch --- 这些的花括号后只要1个空格.)
• 方法(method),函数( function), if, else, do, for, while, switch的右花括号后要换行；
• class, struct, union的右花括号后要换行并插入新空行。.（原文有写Semi-colon,不理解含义）；
• 左花括号后要换行.

注释

• 注释总是从当前缩进开始 "//" 然后紧接一个空格；
• 注释中不允许其他注释；
• 注释要加在注释的对象之后. （译者注：原文 Comments always preceed the construct they address ）；
• 注释中使用完整语句；
• 用于声明的时候，注释可以使用祈使句；

上面这些，是你的代码看起来舒服的指南，也是你的代码更具可读性的指南.

头文件示例：

//  MODULE NAME: ClassName.h

//      PROJECT: CS1344-1,2 Course Notes

//       AUTHOR: Neill Kipp

//         DATE: January 1, 1996

//  DESCRIPTION: This file presents examples of naming and 

//  indentation style in a C++ class declaration.  This title

//  information is minimal.



// The following prevents files from being included

// twice.  It is a naming exception designed to emulate a file name

// (period is not a name character; underscore is).

#ifndef ClassName_h

#define ClassName_h



// This directive includes the superclass declaration.

#include "super.h"



// This directive includes another class declaration.

#include "other.h"



// The comment for an enumeration declaration precedes the declaration.

enum OverflowState

{

    // Each item''s comment precedes it at the same indentation as the item.

    no_overflow,

    

    // Follow the last item with a comma;

    // it helps avoid syntax errors when adding or rearranging items.

    overflow_occurred,

};



// This class shows how naming conventions and comments are used in a

// simple class declaration.  Whitespace precedes and follows reserved

// words (like "public").



class ClassName

{ 

    // After a brace, indent four spaces.

    // The description of the variable "memberData" goes here.

    int memberData;



    // If a line ends in single colon, reverse-indent two spaces.

  public:



    // The constructor gives initial values to member data.

    ClassName();



    // The destructor guarantees clean deallocation.

    // The tilde (~) is part of the method name.  It is not an operator.

    ~ClassName();



    // This method increments the member variable by the value in "howMuch" 

    // and returns TRUE if overflow is detected (FALSE otherwise).  Method 

    // comments tell what the method does, what the arguments are,

    // and what the method returns.

    OverflowState IncrementMemberVariable( int howMuch);

    

    // Prints message about overflow.

    void ShowOverflow( OverflowState overflow);

};



#endif

源代码文件示例：

//  MODULE NAME: {域名已经过期}

//      PROJECT: CS1344-1,2 Course Notes

//       AUTHOR: Neill Kipp

//         DATE: January 1, 1996

//  DESCRIPTION: This file presents examples of naming and 

//  indentation style in a C++ class implementation.  This title

//  information is minimal.



// This directive includes header information for the "ClassName" class.

#include "ClassName.h"



ClassName::ClassName()

{

    // Initialize member data (statement comments are in the imperative,

    // and preceed the statement).  Suggestion: write the comments first, then

    // write the code.

    memberData = 0;

}



// The return type appears on the first line,

// followed by the class name colon-colon on the second,

// and finally the method name on the last.  Then a newline, an open brace

// and then indent.  Notice the space after the open parenthesis.  It helps

// the eye catch the type name.

OverflowState

ClassName::IncrementMemberVariable( int howMuch)

{

    // Check the overflow condition.

    if ( TOO_BIG - memberVariable > howMuch) {

 // If overflow, return that overflow occurred.

 return overflow_occurred;

    } else {

 // Otherwise, return overflow is ok.

 return overflow_none;

    }

}



// This code implements the ShowOverflow method.

void

ClassName::ShowOverflow( OverflowState overflow)

{

    // Switch is a reserved word.  It is followed by a space.

    switch ( overflow) {



 // Lines ending in a colon reverse indent two spaces.

      case no_overflow:

 // Display message about no overflow.

 cout << "No overflow occurred.\n";

 break;



      case overflow_occurred:

 // Display message that overflow occurred.

 cout << "Warning: overflow occurred.\n";

 break;

    }

}

其他例子：

// Note the spacing and indentation in the for statement.

for ( whichItem = 0; whichItem < BIG_NUMBER; whichItem++) {

    DoSomething( whichItem);

}



// Bang is not followed by a space.

while ( !SemaphoreOK()) {

    DoWaitForSemaphore( LONG_TIME);

}