软件编码规范

软件编码规范
前言：

    通过建立代码编写规范，形成BCB 开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性、一致性，保证程序代码的质量，继承软件开发成果，充分利用资源。提高程序的可继承性，使开发人员之间的工作成果可以共享。

软件编码要遵循以下原则:
1.遵循开发流程，在设计的指导下进行代码编写。
2.代码的编写以实现设计的功能和性能为目标，要求正确完成设计要求的功能，达到设计的性能。
3.程序具有良好的程序结构，提高程序的封装性好，减低程序的耦合程度。
4.程序可读性强，易于理解；方便调试和测试，可测试性好。
5.易于使用和维护；良好的修改性、扩充性；可重用性强/移植性好。
6.占用资源少，以低代价完成任务。
7.在不降低程序的可读性的情况下，尽量提高代码的执行效率。

本规范的描述主要以 Borland C++ Builder 语言为例

一、    规范：以下对本规范作详细说明。

1：源程序的文件管理：
a)组织：每个程序文件单元通常都应由 .cpp、.dfm和 .h 等文件组成，并将单元的公共声明部分放在 .h 文件中。划分单元主要是以类为依据，原则上每个较大的类都应为一个单独的单元，但在类较小且多个小类关系密切等情况下也可几个类共一个单元（建议仅对已经详细测试的较为通用的类采用）。
b)命名：原程序文件命名采用有意义的格式。例如：对登陆程序来说三个文件的命名应该是这样，.cpp的是 Login.cpp  .dfm的是Login.dfm  .h的是Login.h
c)文件结构：每个程序文件由标题、内容和附加说明三部分组成。
  (A)标题：文件最前面的注释说明，其内容主要包括：程序名，作者，版本信息，简要说明等，必要时应有更详尽的说明（将以此部分以空行隔开单独注释）。
  (B)内容：为文件源代码部分基本上按预处理语句、类型定义、变量定义、函数原型、函数实现（仅对 .cpp 文件）的顺序。 main 、 winmain ，控件注册等函数应放在内容部分的最后，类的定义按 private 、 protected 、 pubilic 、 __pubished 的顺序，并尽量保持每一部分只有一个，各部分中按数据、函数、属性、事件的顺序。
  (C)附加说明：文件末尾的补充说明，如参考资料等，若内容不多也可放在标题部分的最后。
举例说明：
/*************************************************************
类：class TimageManipulation
设计者：lunhongjun (2001/05/09)
用途：用于图象处理，实现图象亮度、对比度、反白、色彩平衡等处理

版本：
    1.0    2001/05/09      完成基本的图象处理功能设计
            2001/05/10      修改完成一个小Bug.
*************************************************************/
class TImageManipulation
{
private://define variant
    Graphics::TBitmap * pSourceBitmap;//用于存放未经处理的原始图像
    Graphics::TBitmap * pManipulatedImage;//用处存放经过处理后的图象
    //图像处理过程中的相关参数
    int    iBrightness;          //色彩亮度
    int    iContrast;            //色彩对比度
    int    iRedColorBalance;    //红色色彩平衡度
    int    iBlueColorBalance;    //蓝色色彩平衡度
    int    iGreenColorBalance;  //绿色色彩平衡度
    bool    bRotate;              //字体旋转度数
    bool    bMonochrome;            //是否反白显示
private:
    void __fastcall BrightnessImage(void);//调整图象亮度
    void __fastcall ContrastImage(void);//调整图象对比度
    void __fastcall DoManipulationImage(void);//图象处理
    void __fastcall MonochromeImage(void);//图象反白
    void __fastcall DoColor(void);
    void __fastcall DoFilter(int * flt, int Div);
    void __fastcall RotateImage(void);//调整图象色彩平衡

public://define property ,method,event,function
    __fastcall TImageManipulation();
__fastcall ~TImageManipulation();

    void __fastcall DoBrightness(int BrightnessIncrement);
    void __fastcall DoContrast(int ContrastIncrement);
    void __fastcall DoMonochrome(void);
    void __fastcall DoChangeColorBalance(int RedBalance,
    int BlueBalance, int GreenBalance);
    void __fastcall SetSourceImage(Classes::TPersistent* Source);
    Graphics::TBitmap * __fastcall GetManipulationImage(void);
    void __fastcall DoBlur(void);
    void __fastcall DoSharp(void);
    void __fastcall DoEmboss(void);
    void __fastcall LoadImageFromFile(AnsiString FileName);
    void __fastcall SaveManipulatedImageAsFile(AnsiString FileName);
    TImageManipulation& operator=(const TImageManipulation & imSource);
    void __fastcall DoRotate(void);
};
#endif

2．编辑风格：

（1）缩进

缩进以4个空格为单位。建议在Tools/Editor Options中设置General页面的Block ident为4，Tab Stop为4，不要选中Use tab character。预处理语句、全局数据、函数原型、标题、附加说明、函数说明、标号等均顶格书写。语句块的“{”“}”配对对齐，并与其前一行对齐，语句块类的语句缩进建议每个“{”“}”单独占一行。

（2）空格

变量、类、常量数据和函数在其类型，修饰（如 __fastcall 等）名称之间适当空格并据情况对齐。关键字原则上空一格，如： if ( ... ) 等，运算符的空格规定如下：“::”、“->”、“[”、“]”、“++”、“--”、“~”、“!”、“+”、“-”（指正负号），“&”（取址或引用）、“*”（指使用指针时）等几个运算符两边不加空格（其中单目运算符系指与操作数相连的一边），其它运算符（包括大多数二目运算符和三目运算符“?:”两边均加一空格，“(”、“)”运算符在其内侧空一格，在作函数定义时还可据情况多空或不空格来对齐，但在函数实现时可以不用。“,”运算符只在其后空一格，需对齐时也可不空或多空格，“sizeof”运算符建议也在其后空一格，不论是否有括号，对语句行后加的注释应用适当空格与语句隔开并尽可能对齐。

（3）对齐

原则上关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。另每一行的长度不应超过屏幕太多，必要时适当换行，换行时尽可能在“,”处或运算符处，换行后最好以运算符打头，并且以下各行均以该语句首行缩进，但该语句仍以首行的缩进为准，即如其下一行为“{”应与首行对齐。
变量定义最好通过添加空格形成对齐，同一类型的变量最好放在一起。如下例所示：
int        Value;
int        Result;
int        Length;
DWORD      Size;
DWORD      BufSize;
char *      pBuf;
void *      pOutputBuf;
LPCSTR *    pPath;

（4）空行

程序文件结构各部分之间空两行，若不必要也可只空一行，各函数实现之间一般空两行，由于BCB会自动产生一行“//------”做分隔，另因每个函数还要有函数说明注释，故通常只需空一行或不空，但对于没有函数说明的情况至少应再空一行。对自己写的函数，建议也加上“//------”做分隔。函数内部数据与代码之间应空至少一行，代码中适当处应以空行空开，建议在代码中出现变量声明时，在其前空一行。类中四个“p”之间至少空一行，在其中的数据与函数之间也应空行。

（5）注释

对注释有以下三点要求：
A.必须是有意义。
B.必须正确的描述了程序。
C.必须是最新的。
注释必不可少，但也不应过多，以下是四种必要的注释：
A.标题、附加说明。
B.函数说明。对几乎每个函数都应有适当的说明，通常加在函数实现之前，在没有函数实现部分的情况下则加在函数原型前，其内容主要是函数的功能、目的、算法等说明，参数说明、返回值说明等，必要时还要有一些如特别的软硬件要求等说明。
C.在代码不明晰或不可移植处必须有一定的说明。
D.及少量的其它注释。
注释有块注释和行注释两种，分别是指：“/**/”和“//”建议对A用块注释，D用行注释，B、C则视情况而定，但应统一，至少在一个单元中B类注释形式应统一。
举例如下：
/***************************************************************************
函数名称：ResultType MyFunction(ParamType1 Param1, ParamTyp2,Param2)
功能：该函数主要是完成如下的功能
设计目的：设计该函数主要是为了解决。。。
设计原理：该函数是这样设计的。。。
实现方法/过程：为了实现函数的目的，这个函数是这样实现的。。。
出入口参数：
    ParamType1 Param1：类型ParamType1，这个参数是。。。
    。。。
返回值描述：
设计修改日志：
    2001/4/16    第一次设计
    2001/4/17    修改了。。。
    2001/4/18    添加了。。。删除了。。。
相关函数：
其他补充说明：
**************************************************************************/
ResultType MyFunction(ParamType1 Param1, ParamTyp2,Param2)
{
int         Value;
    int         Result;
DWORD Size;
char *    pBuf;
    
    。。。。
}

(6)代码长度：

对于每一个函数建议尽可能控制其代码长度为53行左右，超过53行的代码要重新考虑将其拆分为两个或两个以上的函数。函数拆分规则应该一不破坏原有算法为基础，同时拆分出来的部分应该是可以重复利用的。对于在多个模块或者窗体中都要用到的重复性代码，完全可以将起独立成为一个具备公用性质的函数，放置于一个公用模块中(Common.cpp/Common.h)

3．符号名的命名（包括变量、函数、标号、模块名等）

选用有实际意义的英文标识符号或缩写符号，名称中尽可能不使用阿拉伯数字，如这样的名称是不提倡的：Value1,Value2,Value3,Value4…..。
例如：
file(文件),code(编号),data(数据),pagepoint(页面指针), faxcode(传真号) ,address(地址),bank(开户银行),……
变量名称:由（前缀+修饰语）构成。
（1）生存期修饰：用l（local）表示局域变量，p(public)表示全局变量，s(send)表示参数变量
（2）类型修饰：用s(AnsiString)表示字符串,c(Char)表示字符,n(number)数值,i(intger)表示整数,d(double)表示双精度,f(float)浮点型,b(bool)布尔型,d(date)表示日期型.
例如：
li_length表示整形的局域变量,是用来标识长度的.ls_code表示字符型的局域变量,用来标识代码.
控件名称：由（前缀+修饰语）构成。前缀即为控件的名称。

按钮变量  Button+Xxxxxxx    例如：ButtonSave,ButtonExit,ButtonPrint等
题标变量  Label+Xxxxxxxx    例如：LabelName,LabelSex等
数据表变量 Table+Xxxxxx      例如：TableFile,TableCount等
查询变量  Query+Xxxxxx      例如：QueryFile,QueryCeneter等
数据源变量 DataSource+Xxx      例如：DataSourceFile,DataSourceCenter等
。。。。。。。。。。。。。。。。
(注：对于与表有关的控件“修饰语”部分最好直接用表名。)

4：输入输出

输入和输出方式和格式尽可能方便用户，避免因设计不当给使用带来麻烦。应根据不同用户的类型、特点和不同的要求来制定方案。格式力求简单，并应有完备的出错检查和出错恢复措施。
界面布局主要考虑各区域在屏幕的放置，使用户能以最快的速度找到操作对象、发现目标，屏幕的布局还要考虑界面的表现形式，使界面美观一致，协调合理。界面设计要求满足以下要求：
●界面上只包含必要的信息。
●界面上包含所有必要的信息。
●界面布局从左上角开始。
●制订格式标准，所有的屏幕设计都遵守这些标准，保持一致性。
●根据逻辑关系将相关的信息放在一起。
●屏幕设计要保持对称的平衡。
●避免过多使用前调信息。//例如OnEnter事件请尽量少用。
●区分标题和内容。
●提示信息要简洁。
●设计与用户知识和经验一致。
●按照使用顺序显示信息。
●遵照流行软件的事实标准。
●选择合理的显示方式。
●尽可能不让用户切换画面即可完成一次完整的操作。

5：其它程序技巧

程序中增加合理适量的注释。程序的注释作为评测考核的一个重要指标。
在程序设计时，应该全面考虑出现可能存在的例外情况的处理。应该有一个良好的错误处理和例外处理机制，在处错误的时候能保证程序能正常运行/退出，不会造成用户的数据丢失/损失。对于发生意外错误或例外是要能记录当时的运行情况并且用户可将这个信息返回给开发人员。
避免使用相似的变量名，变量中尽量不含数字。
同一变量名不要有多种意义。
显示说明所有变量。
注意浮点运算的误差，少用浮点数比较。
注意整数运算的特点。
少用或不用GOTO语句，即使用GOTO不要相互交叉。
尽量少用全局和静态变量。
提高程序的封装性，降低程序各模块的耦合性。
提高程序的可继承性，建立通用的函数库、控件库，使开发人员之间的工作成果可以共享。
说明： 该文档设计人：luhongjun(过江项羽)。
      文档版权归BCB开发团队所有，欢迎大家转载引用，但请注明文档所有者和设计人。未经同意请勿任意修改，不可用于商业目的。