VC知识库BLOG-Panic的小屋-[翻译]程序风格的要素－C 风格指南

程序风格的要素－C++风格指南
作者：Neill Kipp
译者：panic 2005年3月30日
译者序：这是一篇写于1996年1月23日的文章，到现在已经有9个年头了，很陈旧，有可能跟不上形势，但是有些东西仍然值得现在的开发者学习，我翻译这篇文字仅供读者参考。
原文链接：http://www.gamedev.net/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() 类型名，类名，方法名，首字母大写前后缀。 UnixFileName.cc  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: ClassName.cc // 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); }