流程标准：通用编程规范

发布时间：2012-04-05 18:10:24      更新时间：2016-04-21 10:13:06      发布人： 和丽梅      阅读次数：3667

通用编程规范

 

1 目的

 

统一代码编码风格，方便代码的日常维护与二次开发

适用对象

 

研发中心&网站事业部

 

3 程序版式

缩进

【3-1-1】程序块要采用缩进风格编写，缩进的空格数为4个。

【3-1-2】{}语句中的代码都要采用缩进风格。

换行

【3-2-1】较长的语句（>120字符）要分成多行书写。

【3-2-2】长表达式要在低优先级操作符处划分新行，操作符放在新行之首；划分出的新行要再次缩进（即缩进2次），使排版整齐，语句可读。

【3-2-3】若函数或方法中的参数较长，要进行适当的划分。

好 的 风 格

if ((very_longer_variable1 >= very_longer_variable12)         && (very_longer_variable3 <= very_longer_variable14)         && (very_longer_variable5 <= very_longer_variable16)) {     dosomething(); }   for (very_longer_initialization;         very_longer_condition;         very_longer_update) {     dosomething(); }   someMethod(longParameter1, longParameter2, longParameter3,                 longParameter4, longParameter5) {     dosomething(); }

差 的 风 格

if ((very_longer_variable1 >= very_longer_variable12) && (very_longer_variable3 <= very_longer_variable14) && (very_longer_variable5 <= very_longer_variable16)) {     dosomething(); }   /* 超过120个字了 */ for(very_longer_initialization;very_longer_condition;very_longer_update) {     dosomething(); }   someMethod(longParameter1, longParameter2, longParameter3, longParameter4, longParameter5) {     dosomething(); }

代码行

【3-3-1】不允许把多个短语句写在一行中，即一行只写一条语句。

好的风格	差的风格
String value  = “value”； String ret = “return”;	String value, ret; value = “value”; ret = “return”;

 

【3-3-2】if、for、do、while、switch、case、default、break、continue等语句自占一行。

【3-3-3】if、for、do、while等的执行语句部分无论多少都要加花括号{}。

好的风格	差的风格
Switch (var) {     case 1:        XXXXX;        break;     case 2:        YYYYY;        break;     default:        break; }   if (var) {     return true; }	Switch (var) {     case 1:        XXXXX;break;     case 2:        YYYYY;break;     default:break; }           if (var) return true;

对齐

【3-4-1】程序块的分界符{}，“{”跟随在上一行，并且前边有一空格隔开，“}”应独占一行并且位于同一列，同时与引用它们的语句左对齐,“}”后边如果有语句，后边用一空格跟语句隔开。

【3-4-2】在函数体的开始、类的定义、接口的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。

 

好的风格	差的风格
function() { }   do { } while()   for () { }   class {   }	function() { }   do{   /* 没有空格隔开 */ }while()   for (){ }   class { }

空格

【3-5-1】关键字之后必须有空格，以突出关键字。

【3-5-2】函数名、方法名与左括号（之间不应该有空格。

【3-5-3】逗号后面加空格。

【3-5-4】赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加空格。

【3-5-5】"!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。

【3-5-6】"->"、"."、"[]"前后不加空格。

空行

【3-6-1】在每个类声明之后、每个函数定义结束之后都要加空行。

【3-6-2】在一个函数体内，逻揖上密切相关的语句之间不加空行，

其它地方应加空行分隔。

好的风格	差的风格
/* 类的注释 */ class Request { } /* 空行 */ /* 类的注释 */ public class Response {     /* 公有方法的注释 */     public boolean sendResponse() {        check parameters;        /* 空行 */        send response;     }     /* 空行 */     /* 公有方法的注释 */     public void setResult(int result) {       } }	/* 类的注释 */ class Request { } /* 类的注释 */ public class Response {     /* 公有方法的注释 */     public boolean sendResponse() {        check parameters;        send response;     }   /* 空了太多的空行 */     /* 公有方法的注释 */     public void setResult(int result) {       } }

4 注释

版权信息

【4-1-1】程序文件头部应进行注释，注释必须列出：版权说明、生成日期、作者、描述等。

示例如下，当然，并不局限于此格式，但上述信息要包含在内，并且项目组内要统一。

/**

 * Copyright (C) 2006-2012 Tuniu All rights reserved

 * Author：zhaiweisen

 * Date：YYYY-MM-DD

 * Description: ZZZZZZZZ

 */

 

【4-1-2】如果在2013年改动了该文件，那么文件头部里的版权年份要改为2013,不修改则不用改版权年份。

【4-1-3】程序里和注释里的日期格式统一用YYYY-MM-DD。

类、方法、函数注释

【4-2-1】类的顶部要加上类的作用说明，注释采用/* */方式。

/**

 * Http client class.

* Sends the data to server and gets the response from server.

 *

 */

public class Request {

}

 

【4-2-2】函数（包括类的公有方法、私有方法、保护方法），要说明函数的作用、出参、入参、返回值，如果有调用的注意事项，也要进行说明，注释采用/* */方式，注释的风格要符合所使用语言的规则，如使用@param，@return等等。

/**

 * Sends the data to server

 *

 *  url: the url of server

 *  data: data be sent to server

 *  return value: return the response from server

*/

boolean send(String url, String data) {

 

}

 

【4-2-3】如果修改函数功能或是Fix Bug，需要在函数顶部加上相关说明，注释采用//方式。

/**

 * Sends the data to server

 *

 *  url: the url of server

 *  data: data be sent to server

 *  return value: return the response from server

*/

// modify by zhaiweisen for bugXXXXX（when sending NULL data, server crashed）

// modify by ligang for bugYYYYYY (when URL is illegal, it throws exception)

boolean send(String url, String data) {

 

}

文件注释

【4-3-1】配置文件、脚本文件,应尽可能的加上注释语句，说明配置方法、使用方法、用途等等，方便使用。

注释规则

【4-4-1】如果代码本来就是清楚的，则不必加注释，避免画蛇添足。

【4-4-2】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性，不再有用的注释要删除，不再有用的代码也要删除，不允许用注释的方法保留下来。

【4-4-3】注释应当准确、易懂，防止注释有二义性，错误的注释不但无益反而有害。

【4-4-4】尽量避免在注释中使用缩写，特别是不常用缩写。

【4-4-5】注释的位置只可以放在代码的上方，不可放在右边或下方。

好的风格	差的风格
public boolean send() {     /* put your comments here */     checkParameters();       /* put your comments here */     sendResponse(); }	public boolean send() {     checkParameters();     /* DO NOT put your comments here */       sendResponse();/* DO NOT put your comments here */ }

 

【建议】注释的比例在20%-30%左右。

 

5 命名规则

标识符

【5-1-1】标识符的命名要清晰、明了，有明确含义。

【5-1-2】使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写。

示例如下：

temp 可缩写为  tmp；

flag 可缩写为  flg；

message 可缩写为  msg；

【5-1-3】标识符的命名全部使用英文，不允许出现拼音。

【5-1-4】当用来表示同一个逻辑的新方法或者新文件时，

在方法名或者文件名中不允许出现new,new2之类的词，必须使用V1，V2来表示。

【5-1-5】专用术语，缩写命名，参照Wiki上的术语规范。

常量

【5-2-1】常量全部大写，并用下划线连接。

好的风格	差的风格
const char* METHOD_GET = ”get”;	const char* method-get = ”get”;

【5-2-2】常量要加上const或是final等不可修改的修饰符。

【5-2-3】错误码要用常量定义,并用ERROR_开头

好的风格	差的风格
final int ERROR_HTTP_TIMEOUT = -1;	int HTTP_TIMEOUT = -1;

变量

【5-3-1】禁止取单个字符（如i、j、k...），建议除了要有具体含义外，还能表明其变量类型、数据类型等。

【5-3-2】命名规范必须与所使用的系统风格保持一致，并在同一项目中统一。

【5-3-3】不要让局部变量覆盖全局变量。

好的风格	差的风格
int TOTAL_NUM = 0; void add(int diyNum, int hotelNum) {     int sum = diyNum + hotelNum;     … }	int TOTAL_NUM = 0; void add(int diyNum, int hotelNum) {     int TOTAL_NUM = diyNum + hotelNum;     … }

【5-3-4】不要让局部变量覆盖参数。

好的风格	差的风格
void add(int diyNum, int hotelNum) {     int totalNum = diyNum + hotelNum;     … }	void add(int diyNum, int hotelNum) {     int diyNum = diyNum + hotelNum;     … }

【5-3-5】严禁使用大小写不一样的同名变量。

好的风格	差的风格
void add(int diyNum, int hotelNum) {     int totalNum;     int sum; }	void add(int diyNum, int hotelNum) {     int totalNum;     int TotalNum; }

【5-3-6】变量都要有初始值,并且声明和初始值写在同一行。

好的风格	差的风格
int add(int diyNum, int hotelNum) {     int totalNum = diyNum + hotelNum;     int sum = 0;     int numNum = 10;       /* do something here */     if () {        return sum;     } else {        sum = totalNum + newNum;        return sum;     } }	int add(int diyNum, int hotelNum) {     int totalNum = diyNum + hotelNum;     int sum;     int numNum;       /* do something here */     if () {        return sum;     } else {        newNum = 10;        sum = totalNum + newNum;        return sum;     } }

【5-3-7】同一个变量不能在作用域内移作他用。

好的风格	差的风格
int add(int diyNum, int hotelNum) {     int totalNum = diyNum + hotelNum;     int index = 0;       for (index = 0; index < totalNum; index++) {         /* do something */     } }	int add(int diyNum, int hotelNum) {     int totalNum = diyNum + hotelNum;         for (totalNum = 0; totalNum < diyNum + hotelNum; totalNum++) {         /* do something */     } }

【5-3-8】全局变量用大写，并且用下划线分割。

类命名

【5-4-1】类名的所有单词的首字母大写。

【5-4-2】不要用下划线做类名单词连接符。

好的风格	差的风格
public class HttpResponse { }   public class RestMethod { }	public class httpresponse { }   public class rest_method { }

方法、函数命名

【5-5-1】方法使用英文的大小写来分隔单词，第一个单词的首字母小写，其余单词的首字母大写。

 

【5-5-2】命名使用动词+名词的方式；

【5-5-3】用正确的反义词组命名具有相反动作的函数等

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

add / remove       begin / end        create / destroy

insert / delete    first / last       get / set

increment / decrement   add / delete  lock / unlock      open / close          min / max          old / new          start / stop          next / previous    source / target    show / hide              send / receive    

source / destination    up / down

6 基本语句

语句

【6-1-1】不可将布尔变量直接与TRUE、FALSE或者1、0进行比较。

好的风格	差的风格
void functionA(boolean isSet) {     if (isSet) {     } else {     } } PHP通过下面的方式判断 void functionA(boolean isSet) {     if (isSet===true) {     } else {     } }	void functionA(boolean isSet) {     if (isSet == true) {     } else {     } }

 

【6-1-2】如果因为修改bug而增加了else if分支，需要在新增加

的else if分支上边加上//注释，并且”else if {”要另起一行。

好的风格	差的风格
修改前： if (METHOD.GET == type) {     /* do something */ } else if(METHOD.POST == type) {     /* do something */ } else {     /* do something */ }   修改后： if (METHOD.GET == type) {     /* do something */ } else if (METHOD.POST == type) {     /* do something */ } // fix bug for delete method else if (METHOD.DELETE == type) {     /* do something */ } else {     /* do something */ }	修改前： if (METHOD.GET == type) {     /* do something */ } else if(METHOD.POST == type) {     /* do something */ } else {     /* do something */ }   修改后： if (METHOD.GET == type) {     /* do something */ } else if (METHOD.POST == type) {     /* do something */ } else if (METHOD.DELETE == type) {     /* do something */ } else {     /* do something */ }

 

【6-1-3】if语句缺省要有else 。

 

【6-1-4】在比较的时候，将常量写在左边。

void sendRequest(String method，String data) {

    if (HTTP.GET == method) {

 

    } else {

 

    }

}

 

语句

【6-2-1】每个case语句的结尾不要忘了加break。

【6-2-2】不允许从上一个case跑到下一个case。

【6-2-3】缺省要有default分支。

好的风格	差的风格
void functionA(int type) {     switch (type) {         case A:             break;         case B:             break;         default:             break;     } }	void functionA(int type) {     switch (type) {         case A:             break;         case B:             break;     } }

循环语句

【建议】在多重循环中，应当将最长的循环放在最内层，最短的循环放在最外层，以减少CPU跨切循环层的次数。

推荐的风格	别的风格
for (col = 0; col < 5; col++) {     for (row = 0; row < 100; row++) {         sum = sum + a[row][col];     } }	for (row = 0; row < 100; row++) {     for (col = 0; col < 5; col++) {         sum = sum + a[row][col];     } }

 

运算符

【6-4-1】注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。

 运算符的优先级如下：

优先级	运算符	结合律
从   高   到   低   排   列	( )  [ ]  ->  .	从左至右
	!  ~  ++  --  （类型） sizeof +  -  *  &	从右至左
	*  /  %	从左至右
	+  -	从左至右
	<<  >>	从左至右
	<   <=   >  >=	从左至右
	==  !=	从左至右
	&	从左至右
	^	从左至右
	|	从左至右
	&&	从左至右
	||	从右至左
	?:	从右至左
	=  +=  -=  *=  /=  %=  &=  ^= |=  <<=  >>=	从左至右

 

【6-4-2】三元操作符、 二元操作符的里边如果有运算，一定要用 括号括起来。

好的风格	差的风格
result = ((numA + numB) > 0) ? numA : numB;	result = numA + numB > 0 ? numA : numB;

 

【6-4-3】三元操作符， 二元操作符的里边的运算应该尽可能的简单， 不允许利用操作符进行赋值操作。

好的风格	差的风格
if (1 == a) {     b = 1; } if (2 != c) {     d = 0; }	a == 1 && b = 1; c != 2 || d = 0；

 

7 函数、方法设计

【7-1】对所调用函数的错误返回码要仔细、全面地处理。

好的风格	差的风格
int functionA() {     int ret = callOtherFunction();     if (OK > ret) {        return ERROR;     } else {     } }	int functionA() {     callOtherFunction();     /* Unchecking return value,continue to do */     … }

【7-2】函数的规模尽量限制在200行以内。

【7-3】一个函数仅完成一件功能。

【7-4】不要设计多用途面面俱到的函数。

【7-5】避免设计多参数函数，如果参数过多，可考虑将参数进行封装，比如做成类或是结构体。函数的参数不允许超过5个。

【7-6】参数命名要恰当，顺序要合理。

例如编写字符串拷贝函数StringCopy，它有两个参数。如果把参数名字起为str1和str2，例如 void StringCopy(char *str1, char *str2);

那么我们很难搞清楚究竟是把str1拷贝到str2中，还是刚好倒过来。可以把参数名字起得更有意义，如叫strSource和strDestination。这样从名字上就可以看出应该把strSource拷贝到strDestination。

还有一个问题，这两个参数那一个该在前那一个该在后？参数的顺序要遵循程序员的习惯。一般地，应将目的参数放在前面，源参数放在后面。

如果将函数声明为：

void StringCopy(char *strSource, char *strDestination);

别人在使用时可能会不假思索地写成如下形式：

char str[20];

StringCopy（str, “hello World”）;

【7-7】检查函数所有输入参数的有效性。

好的风格	差的风格
int functionA(String name) {     if (NULL == name) {        return ERROR;     } else {        int ret =          callOtherFunction(name);     }     … }	int functionA(String name) {     int ret = callOtherFunction(name);     … }

 

8 程序效率

【8-1】编程时要经常注意代码的效率。

在进行数据结构设计时，要考虑不同的数据类型，如array,set,map,list,tree的优缺点，根据程序的特点，选择正确的数据结构。

在保证软件系统的正确性、稳定性、可读性及可测性的前提下，提高代码效率。

不能一味地追求代码效率，而对软件的正确性、稳定性、可读性及可测性造成影响。

【8-2】在保证程序质量的前提下，通过压缩代码量、去掉不必要代码以及减少不必要的局部和全局变量，来提高效率。

【8-3】尽量减少循环嵌套层次。

 

9 程序质量

【9-1】编程时要经常注意代码的质量。

【9-2】要注意资源的使用、释放情况。

如文件open之后，正常异常情况下都会被close。

【9-3】认真处理程序所能遇到的各种异常情况。

【9-4】严禁随意更改其它模块或系统的有关设置和配置。

【9-5】不能随意改变与其它模块的接口。

【9-6】编程时，要防止差1错误。

说明：此类错误一般是由于把“<=”误写成“<”或“>=”误写成“>”等造成的，由此引起的后果，很多情况下是很严重的，所以编程时，一定要在这些地方小心。当编完程序后，应对这些操作符进行彻底检查

【9-7】使用变量时要注意其边界值的情况。

10 编译、审查、提交

【10-1】通过代码走读及审查方式对代码进行检查。

说 明：代码走读主要是对程序的编程风格如注释、命名等以及编程时易出错的内容进行检查，可由开发人员自己或开发人员交叉的方式进行；代码审查主要是对程序实 现的功能及程序的稳定性、安全性、可靠性等进行检查及评审，可通过自审、交叉审核或指定部门抽查等方式进行。代码走读之前利用公司统一规定的代码检查工具 进行检查，提高效率。

【10-2】使用代码检查工具对源程序检查。

【10-3】在产品软件（项目组）中，最好使用相同的编辑器，并使用

相同的设置选项。

【10-4】提交到SVN，一定要写上log。

log的格式如下：

如果是完成一个新的功能，用[imp]开头

如果是修改现有逻辑的，用[mod]开头

如果是修改bug的，用[fix]开头，后边紧跟bug号

如果是revert的，用[rev]开头，后边要有版本号

如果是delete的，用[del]开头，并说明删除的原因

revision1:

[imp]

implement the base64 encode and decode

 

revision2:

[mod]

update the logic of base64 encode

 

revision3:

[rev]

revert revisionxxx

 

revision4:

[fix]bug-number

fix the crash when decoding chinese characters.

reviewed by xxxxx

 

[del]

delete xxx.java because it is committed by mistake.

 

【10-5】提交到SVN，如果是fix bug,一定要进行严格的review,并且在提交的时候写上code reviewer的名字。

【10-6】一次只提交同一个逻辑功能的文件。不要将不同逻辑的修改一次性提交。

比如这次增加了二次分单的功能，并且修改了订单中的一个bug,那么请分成2次提交，一次提交新功能，一次提交bug，不要混合在一起提交。

【10-7】SVN的log，内容要简洁、清楚，便于查询或是日后追踪。

【10-8】所有的代码都要进入SVN,严禁不经过SVN直接进入生产环境。

施行时间

2012年4月5日

附则

本标准最终解释权归研发中心&网站事业部所有。

 

 

 

 

附件：

 

说明：流程标准可能会随实际情况做修订，应以网上文件为准，不应以打印的文档为准。             流程标准文件内容方面的疑问可联系版本更新记录中的最后一次更新人。

 

 

留言板
流程讨论	Re: 通用编程规范     于2012-10-18 16:57:27发表
留言人：黄维荣 部门：   职务：  基础员工	附件下载失败。。

 

 

发表回复

            回复标题：