软件编码规范Word格式.docx

软件编码规范Word格式.docx

《软件编码规范Word格式.docx》由会员分享，可在线阅读，更多相关《软件编码规范Word格式.docx（30页珍藏版）》请在冰豆网上搜索。

Operatingsystemindependencefile.

DateModificationName

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

05/Jan/2007CreatedXX

***********************************************************************/

1.2头文件的结构

头文件由三部分内容组成：

（1）头文件开头处的版权和版本声明。

（2）预处理块。

（3）结构体等数据结构类型声明。

（4）函数声明等。

相关规则

●为了防止头文件被重复引用，应当用ifndef/define/endif结构产生预处理块。

●#include<

filename.h>

格式来引用标准库的头文件（编译器从标准库目录开始搜索）。

●#include“filename.h”格式来引用非标准库的头文件（编译器将从用户的工作目录开始搜索）。

●头文件中只存放“声明”，而不存放“定义”。

●头文件不能相互引用。

●少用全局变量，故尽量不要在头文件中出现如externintvalue这类声明。

版权和版本声明，此处省略。

#ifndef__CSOS_H防止csos.h被重复引用

#define__CSOS_H

#include<

math.h>

引用标准库的头文件

…

#include“myheader.h”引用非标准库的头文件

voidFunction1（…）;

全局函数声明

typedefstructDataCtrlBlk_s结构体声明

{

}DataCtrlBlk_t;

#endif/*#ifndef__CSOS_H*/

1.3定义文件的结构

定义文件有三部分内容：

（1）定义文件开头处的版权和版本声明。

（2）对一些头文件的引用。

（3）程序的实现体（包括数据和代码）。

#include“csos.h”引用头文件

全局函数的实现体

voidFunction1（…）

}

1.4头文件的作用

（1）通过头文件来调用库功能。

用户只需要按照头文件中的接口声明来调用库功能，而不必关心接口怎么实现的。

编译器会从库中提取相应的代码。

（2）头文件能加强类型安全检查。

如果某个接口被实现或被使用时，其方式与头文件中的声明不一致，编译器就会指出错误。

●维护用户库。

1.5目录结构

通常应将头文件和定义文件分别保存于不同的目录，以便于维护。

●将头文件保存于include目录，

●将定义文件保存于source目录（可以是多级目录）。

●如果某些头文件是私有的，这些私有的头文件可以和定义文件存放于同一个目录。

✓软件编码在全局上应保证可维护性。

2标识符

标识符的命名要清晰，明了，有明确含义，使用完整的单词或大家基本可以理解的缩写，避免产生误解，命名须词要达意，命名规范必须与所使用的系统风格保持一致，在同一项目中统一。

2.1命名规范

●Hungary命名法：

举例：

GfxDrawText（）

●Posix命名法：

有的第三方软件使用本方法，故移植这样的第三方软件（ipanel,hdrd.etc），可以使用本方法以保持符号命名方法的一致。

举例：

ipanel_porting_filter_recv（）

●混合方法：

综合上述二方法中的一种方法，CS软件体系将采用本方法，如CSAPI。

CSUART_SetBaudrate（）

注：

过程别名，双下划线开头，用于某过程的另一种实现。

如：

__CSUART_SetBaudrate（）

2.2取名

特定意义的符号名由名词及动词组成，如CSAPI的取名规定为：

模块名_操作（行为+对象），增加模块名可以有效防止冲突；

操作部分中的行为使用正确的反义词组命名具有相反动作（函数），及互斥意义的变量（参数）。

✓举例数据结构取名

flash_DevCtrlBlock;

✓举例行为取名

●Abort：

中止已经执行的过程

●Cancel：

取消尚未执行的过程

●Flush：

清洗缓存，数据传入目标

●Discard：

丢弃操作对象

●Get：

对象为buffer（cache）

●Set：

●Load：

对象为externaldevice:

ramdiskhdd,如dbase

●Save：

●Read：

对象为devicedriver

●Write：

●Init/allocate：

初始化对象

●Open：

打开对象

●Close：

●Term/deallocate：

说明：

下面是一些在软件中常用的反义词组。

add/remove 

add/delete 

begin/end 

create/destroy

insert/delete 

get/setincrement/decrement

put/get 

lock/unlock 

open/close

start/stop 

show/hidecut/paste

send/receive 

read/write 

up/down

next/previousmin/max 

old/new 

source/targetsource/destinationfirst/last 

2.3函数

✓外部函数：

模块名使用大写；

行为部分动词在前，名词在后，为匈牙利写法，原型应在对应的头文件中声明。

✓局部函数：

原型应在的源头文件开头声明

●模块名使用小写；

行为部分动词在前，名词在后，为匈牙利写法，如：

staticstuart_ComputeBaudrate（）

●省略模块名部分，只有行为部分，匈牙利写法

ComputeBaudrate（）

3排版

3.1：

程序块要采用缩进风格编写，缩进的空格数为TAB（定义为2空格）的整数倍，即对齐只使用TAB键，不使用空格键，函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。

对于由开发工具自动生成的代码可以有不一致，编辑器使用sourceinsight

和ultraedit。

3.2：

相对独立的程序块之间、变量说明之后必须加空行。

应如下书写

if（!

valid_ni（ni））

...programcode

空行

repssn_ind=ssn_data[index].repssn_index;

repssn_ni 

=ssn_data[index].ni;

3.3：

较长的语句（>

80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。

示例：

perm_count_msg.head.len=NO7_TO_STAT_PERM_COUNT_LEN

+STAT_SIZE_PER_FRAM*sizeof（_UL）;

act_task_table[frame_id*STAT_TASK_CHECK_NUMBER+index].occupied

=stat_poi[index].occupied;

act_task_table[taskno].duration_true_or_false

=SYS_get_sccp_statistic_state（stat_item）;

report_or_not_flag=（（taskno<

MAX_ACT_TASK_NUMBER）

&

&

（n7stat_stat_item_valid（stat_item））

（act_task_table[taskno].result_data!

=0））;

3.4：

循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首。

if（（taskno<

max_act_task_number）

（n7stat_stat_item_valid（stat_item）））

for（i=0,j=0;

（i<

BufferKeyword[word_index].word_length）

（j<

NewKeyword.word_length）;

i++,j++）

first_word_length）&

second_word_length）;

...programcode

3.5：

不允许把多个短语句写在一行中，即一行只写一条语句。

如下例子不符合规范。

rect.length=0;

rect.width=0;

rect.width 

=0;

3.6：

if、for、do、while、case、switch、default等语句自占一行，程序块的分界符（如C语言的大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。

if（pUserCR==NULL）return;

应如下书写：

if（pUserCR==NULL）

return;

for（...）{

if（...）

{

}

voidexample_fun（void）

应如下书写。

for（...）

3.7：

在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；

进行非对等操作时，如果是关系密切的立即操作符（如－>

），后不应加空格。

采用这种松散方式编写代码的目的是使代码更加清晰。

由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧（即左括号后面和右括号前面）不需要加空格，多重括号间不必加空格，因为在C/C++语言中括号已经是最清晰的标志了。

在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。

给操作符留空格时不要连续留两个以上空格。

（1）逗号、分号只在后面加空格。

inta,b,c;

（2）比较操作符,赋值操作符"

="

、"

+="

，算术操作符"

+"

、"

%"

，逻辑操作符"

"

，位域操作符"

<

^"

等双目操作符的前后加空格。

if（current_time>

=MAX_TIME_VALUE）

a=b+c;

a*=2;

a=b^2;

（3）"

!

~"

++"

--"

（地址运算符）等单目操作符前后不加空格。

*p='

a'

;

内容操作"

*"

与内容之间

flag=!

isEmpty;

非操作"

p=&

mem;

地址操作"

与内容之间

i++;

"

"

（4）"

->

."

前后不加空格。

p->

id=pid;

指针前后不加空格

（5）if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。

if（a>

=b&

c>

d）

3.8：

一行程序以小于80字符为宜，不要写得过长。

4注释

注释应在编写代码时同步进行，修改代码同时修改相应的注释，以保证注释与代码的一致性。

不再有用的注释要删除，注释的内容要清楚、明了，含义准确，防止注释二义性，不使用缩写，注释格式统一，使用C风格“/*……*/”。

4.1：

一般情况下，源程序有效注释量必须在20％以上。

注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。

4.2：

说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：

版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。

/*************************************************

Copyright（C）

Filename:

文件名

Description:

用于详细说明此程序文件完成的主要功能，与其他模块

或函数的接口，输出值、取值范围、含义及参数间的控

制、顺序、独立或依赖等关系

History:

修改历史记录列表，每条修改记录应包括修改日期、修改

者及修改内容简述 

author>

<

time>

version>

desc>

FunctionList:

主要函数列表，每条记录应包括函数名及功能简要说明

*************************************************/

4.3：

源文件头部应进行注释，列出：

版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。

/************************************************************

FileName:

test.cpp

模块描述 

历史修改记录

StaticFunctionList:

主要局部函数及其功能

***********************************************************/

Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。

History是修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述。

4.4：

函数头部应进行注释，列出：

函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。

下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

Function:

函数名称

函数功能、性能等的描述

Calls:

被本函数调用的函数清单

CalledBy:

调用本函数的函数清单

TableAccessed:

被访问的表（此项仅对于牵扯到数据库操作的程序）

TableUpdated:

被修改的表（此项仅对于牵扯到数据库操作的程序）

Input:

输入参数说明，包括每个参数的作

用、取值说明及参数间关系。

Output:

对输出参数的说明。

Return:

函数返回值的说明

Others:

其它说明

4.5：

注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

例1：

/*getreplicatesubsystemindexandnetindicator*/

repssn_ni=ssn_data[index].ni;

例2：

4.6：

通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。

清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

4.7：

对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。

变量、常量、宏的注释应放在其上方相邻位置或右方。

/*activestatistictasknumber*/

#defineMAX_ACT_TASK_NUMBER1000

#defineMAX_ACT_TASK_NUMBER1000/*activestatistictasknumber*/

4.8：

数据结构声明（包括数组、结构、类、枚举等），如果其命名不是充分自注释的，必须加以注释。

对数据结构的注释应放在其上方相邻位置，不可放在下面；

对结构中的每个域的注释放在此域的右方。

可按如下形式说明枚举/数据/联合结构。

/*sccpinterfacewithsccpuserprimitivemessagename*/

enum 

SCCP_USER_PRIMITIVE

N_UNITDATA_IND,/*sccpnotifysccpuserunitdatacome*/

N_NOTICE_IND, 

/*sccpnotifyusertheNo.7networkcannot*/

/*transmissionthismessage*/

N_UNITDATA_REQ,/*sccpuser'

sunitdatatransmissionrequest*/

};

全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。

/*TheErrorCodewhenSCCPtranslate*/

/*GlobalTitlefailure,asfollows*/ 

变量作用、含义

/*0－SUCCESS 

1－GTTableerror*/

/*2－GTerror 

Others－nouse 

*/ 

变量取值范围

/*only 

function 

SCCPTranslate（）in*/

/*thismodualcanmodifyit, 

and 

other*/

/*modulecanvisititthroughcall*/

/*the 

functionGetGTTransErrorCode（）*/ 

使用方法

BYTEg_GTTranErrorCode;

4.10：

注释与所描述内容进行同样的缩排。

可使程序排版整齐，并方便注释的阅读与理解。

如下例子，排版不整齐，阅读稍感不方便。

/*codeonecomments*/

CodeBlockOne

/*codetwocomments*/

CodeBl