CodeStyleConventions 代码风格约定

英文原文：

GENERAL
-------


Use real tabs that equal 4 spaces.




Use typically trailing braces everywhere (if, else, functions, structures, typedefs, class definitions, etc.)


if ( x ) {
}




The else statement starts on the same line as the last closing brace.


if ( x ) {
} else {
}


Pad parenthesized expressions with spaces


if ( x ) {
}


Instead of 


if (x) {
}


And


x = ( y * 0.5f );


Instead of


x = (y * 0.5f);


Use precision specification for floating point values unless there is an explicit need for a double.


float f = 0.5f;


Instead of


float f = 0.5;


And


float f = 1.0f;


Instead of


float f = 1.f;




Function names start with an upper case:


void Function( void );




In multi-word function names each word starts with an upper case:


void ThisFunctionDoesSomething( void );




The standard header for functions is:


/*
====================
FunctionName


  Description
====================
*/




Variable names start with a lower case character.


float x;




In multi-word variable names the first word starts with a lower case character and each successive word starts with an upper case.


float maxDistanceFromPlane;




Typedef names use the same naming convention as variables, however they always end with "_t".


typedef int fileHandle_t;




Struct names use the same naming convention as variables, however they always end with "_t".


struct renderEntity_t;




Enum names use the same naming convention as variables, however they always end with  "_t". The enum constants use all upper case characters. Multiple words are separated with an underscore.


enum contact_t {
CONTACT_NONE,
CONTACT_EDGE,
CONTACT_MODELVERTEX,
CONTACT_TRMVERTEX
};




Names of recursive functions end with "_r"


void WalkBSP_r( int node );




Defined names use all upper case characters. Multiple words are separated with an underscore.


#define SIDE_FRONT 0




Use ‘const’ as much as possible.


Use:


const int *p; // pointer to const int
int * const p; // const pointer to int
const int * const p; // const pointer to const int


Don’t use:


int const *p;




CLASSES
-------


The standard header for a class is:


/*
===============================================================================


Description


===============================================================================
*/


Class names start with "id" and each successive word starts with an upper case.


class idVec3;




Class variables have the same naming convention as variables.


class idVec3 {
float x;
float y;
float z;
}




Class methods have the same naming convention as functions.


class idVec3 {
float Length( void ) const;
}


Indent the names of class variables and class methods to make nice columns. The variable type or method return type is in the first column and the variable name or method name is in the second column.


class idVec3 {
float x;
float y;
float z;
float Length( void ) const;
const float * ToFloatPtr( void ) const;
}


The * of the pointer is in the first column because it improves readability when considered part of the type.




Ording of class variables and methods should be as follows:


1. list of friend classes
2. public variables
3. public methods
4. protected variables
5. protected methods
6. private variables
7. private methods


This allows the public interface to be easily found at the beginning of the class.




Always make class methods ‘const’ when they do not modify any class variables.


Avoid use of ‘const_cast’.  When object is needed to be modified, but only const versions are accessible, create a function that clearly gives an editable version of the object.  This keeps the control of the ‘const-ness’ in the hands of the object and not the user.


Return ‘const’ objects unless the general usage of the object is to change its state.  For example, media objects like idDecls should be const to a majority of the code, while idEntity objects tend to have their state modified by a variety of systems, and so are ok to leave
non-const.


Function overloading should be avoided in most cases.  For example, instead of:


const idAnim * GetAnim( int index ) const;
const idAnim * GetAnim( const char *name ) const;
const idAnim * GetAnim( float randomDiversity ) const;


Use:


const idAnim * GetAnimByIndex( int index ) const;
const idAnim * GetAnimByName( const char *name ) const;
const idAnim * GetRandomAnim( float randomDiversity ) const;


Explicitly named functions tend to be less prone to programmer error and inadvertent calls to functions due to wrong data types being passed in as arguments.  Example:


Anim = GetAnim( 0 );


This could be meant as a call to get a random animation, but the compiler would interpret it as a call to get one by index.


Overloading functions for the sake of adding ‘const’ accessible function is allowable:


class idAnimatedEntity : public idEntity {
idAnimator * GetAnimator( void );
const idAnimator * GetAnimator( void ) const;
};


In this case, a const version of GetAnimator was provided in order to allow GetAnimator to be called from const functions.  Since idAnimatedEntity is normally a non-const object, this is allowable.  For a media type, which is normally const, operator overloading should be avoided:


class idDeclMD5 : public idDecl {
const idMD5Anim * GetAnim( animHandle_t handle ) const;
idMD5Anim * GetEditableAnim( animHandle_t handle );
};


id Studio Names
---------------


id<name>Dlg      // dialog class
id<name>Ctrl     // dialog control class
id<name>Frm      // frame window
id<name>View     // view window
id<name>         // any other class




FILE NAMES
---------


Each class should be in a seperate source file unless it makes sense to group several smaller classes.
The file name should be the same as the name of the class without the "id" prefix. (Upper/lower case is preserved.)


class idWinding;


files:


Winding.cpp
Winding.h




When a class spans across multiple files these files have a name that starts with the name of the class without "id", followed by an underscore and a subsection name.


class idRenderWorld;




files:


RenderWorld_load.cpp
RenderWorld_demo.cpp
RenderWorld_portals.cpp


When a class is a public virtual interface to a subsystem the public interface is implemented in a header file with the name of the class without "id". The definition of the class that implements the subsystem is placed in a header file with the name of the class without "id" and ends with "_local.h". The implementation of the subsystem is placed in a cpp file with the name of the class without "id".




class idRenderWorld;


RenderWorld.h // public virtual idRenderWorld interface
RenderWorld_local.h // definition of class idRenderWorldLocal
RenderWorld.cpp // implementation of idRenderWorldLocal

翻译如下：

常规约定

-------

使用常规的tabs相当于4个空格。

 

通常，不管在哪里，都使用尾随的大括号（这些如：if、else、函数、结构体、定义类型、类定义等等）

if ( x ) {

}

 

else语句在同一行上的最后一个大括号开始

if ( x ) {

} else {
}

 

在括号内，空一个空格后再使用表达式或者变量

if ( x ) {

}

而不是

if (x) {

}

还有就是

x = ( y * 0.5f );

而不是

x = (y * 0.5f);

 

 

除非有一个明确的需要一个双精度数值，否则使用浮点值的精度规范

float f =0.5f;

而不是

float f =0.5;

和

float f =1.0f;

而不是

float f =1.f;

 

 

函数名以大写开始:

void Function( void );

 

 

 

在多词函数名中，每个单词以大写开始:

void ThisFunctionDoesSomething( void);

 

 

每个函数开头写的注释的标准是：

/*

====================

函数名

 说明

====================

*/

 

 

变量名以小写字母开头。

float x;

 

 

在多字变量名称的第一个字以小写字符开始的，每一个连续的字开始用大写。

float maxDistanceFromPlane;

 

 

定义类型名的命名规则和变量名的命名规则是一样的，不过定义类型名是以“_t”结尾的。

typedef int fileHandle_t;

 

结构体名的命名规则和变量名的命名规则是一样的，不过结构体名是以“_t”结尾的。

struct renderEntity_t;

 

枚举名的命名规则和变量名的命名规则是一样的，不过枚举名是以“_t”结尾的。枚举常量全部使用大写字符。多个单词的枚举变量名使用下划线将其分隔。

enum contact_t {

   CONTACT_NONE,

   CONTACT_EDGE,

   CONTACT_MODELVERTEX,

   CONTACT_TRMVERTEX

};

 

 

递归函数的名称以“_r”结束

void WalkBSP_r( int node );

 

 

宏定义名全部使用大写字符。多个单词的宏定义名使用下划线将其分隔。

#defineSIDE_FRONT    0

 

 

尽可能地使用“const”

使用

const int*p;       // pointer to const int

int *const p;        // const pointer to int

const int * const p;  // const pointer to const int

而不使用

int const*p;

 

 

 

 

类

-------

每个类的开头的标准是：

/*

===============================================================================

 

    描述

 

===============================================================================

*/

 

 

类名以“id”开始，后面的词以一个大写字符开始。

classidVec3;

 

 

类变量名的命名规则和变量名的命名规则是一样的。

class idVec3 {

float   x;

float   y;

float   z;

}

 

类方法的命名规则和函数的命名规则一样。

class idVec3 {

   float   Length( void ) const;

}

 

 

 

 

为了制作整齐的列，我们会缩进类变量和类方法的变量。变量类型或方法的返回类型是在第一列中，变量名或方法名称在第二列。

class idVec3 {

float         x;

float         y;

float         z;

   float         Length( void ) const;

   constfloat * ToFloatPtr( void ) const;

}

*的指针在第一列,因为它当被认为是部分的类型从而提高了可读性。

 

 

类的变量和方法的顺序应该和下面的一样：

1.列出友元类

2.公有变量

3.公有方法

4.保护变量

5.保护方法

6.私有变量

7.私有方法

这使得公共接口在类的开始很容易发现。

 

当类方法不修改任何类变量时，类方法总是定义为‘const’【常量方法】

 

避免使用“const_cast”。 当对象需要修改时，但只有常量的版本都可以访问，创建一个函数，它清楚地提供了一个可编辑的对象版本。这保证了‘const-ness’的控制权在对象的手中，而不是在用户的手中。

 

除非常规使用的对象是改变其状态的，否则返回‘const’对象。例如，媒体对象，如idDecls在大部分的代码中应该是const，而身份的对象根据各种系统修改状态，并确定非const。

 

在大多数情况下，函数重载应该避免的。例如,而不是:

   constidAnim *   GetAnim( int index ) const;

   constidAnim *   GetAnim( const char *name )const;

   constidAnim *   GetAnim( float randomDiversity) const;

而应使用：

   constidAnim *   GetAnimByIndex( int index )const;

   constidAnim *   GetAnimByName( const char *name) const;

   constidAnim *   GetRandomAnim( floatrandomDiversity ) const;

 

 

 

命名准确、清晰的函数不容易造成编程者的错误，也不容易由于传入错误数据类型的参数而造成不准确的函数调用。例如：

Anim =GetAnim( 0 );

这可能意味着调用得到一个随机的动画，但编译器将其解释为调用一个指数。

 

为了加入“常量”访问功能的重载函数是允许的：

class idAnimatedEntity : publicidEntity {

idAnimator *      GetAnimator( void );

const idAnimator *   GetAnimator( void ) const;

};

在这种情况下，提供一个const的GetAnimator版本，以允许GetAnimator函数能够被const函数调用。因为idAnimatedEntity通常是一个非常量对象,因此这是允许的。对于一个媒体类型,它通常是常量,操作符重载应该避免:

class idDeclMD5 : public idDecl {

const idMD5Anim * GetAnim( animHandle_t handle ) const;

idMD5Anim *    GetEditableAnim( animHandle_t handle );

};

id Studio Names

---------------

id<name>Dlg     // dialog class

id<name>Ctrl    // dialog control class

id<name>Frm     // frame window

id<name>View     //view window

id<name>         //any other class

 

 

文件名

---------

除非是有意义的若干个更小的类，否则每个类应该是在一个单独的源文件。文件名应该是和类的名称没有“id”前缀是一样的。(大/小写是保存。)

class idWinding;

 

files:

 

Winding.cpp

Winding.h

 

 

 

 

 

 

 

当一个类跨越多个文件,这些文件有一个名字,从类的名称没有“id”,其次是下划线和分段的名字。

class idRenderWorld;

 

files:

 

RenderWorld_load.cpp

RenderWorld_demo.cpp

RenderWorld_portals.cpp

 

 When a class is a public virtual interface to a subsystem the public interface is implemented in a header file with the name of the class without "id". The definition of the class that implements the subsystem is placed in a header file with the name of the class without "id" and ends with "_local.h". The implementation of the subsystem is placed in a cpp file with the name of the class without "id".

class idRenderWorld;


RenderWorld.h // public virtual idRenderWorld interface
RenderWorld_local.h // definition of class idRenderWorldLocal
RenderWorld.cpp // implementation of idRenderWorldLocal