手把手教你写_“华为”_的标准注释与文档,以及代码规范
2016-11-20 23:49
351 查看
为什么要写注释呢?为什么要写文档呢?
也许有人会这样问。但是我只想说如果你还在这样问,那么你不仅不是一个优秀的程序员,应该说你是不是程序员都应该受到质疑。
先说一下注释的重要性:
在公司的开发中,我们要明白程序不是写给自己看的,也不是所有的代码都是自己写的,我们不仅需要看别人的代码而且还要把自己的代码交给别人看,团队看。也许还会在你离职以后交给你的接班人看。而且,就算是你写的程序,如果过了很久你再去看的话(相信也会受到一万点真实伤害,脱口而出”这是哪个家伙写的这是什么东西!!!”)所以,程序文档的书写,注释的书写,以及标准的编码规范就非常的重要。(而这些是每一个大学老师都不会交给你的)
一般情况下,源程序的有效注释量必须在20%以上。
说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加上,注释不宜太多。也不能太少。注释语言必须准确、易懂、简洁
说明性文件(如头文件.h文件、inc文件、.def文件、编译说明文件.cfg等)头部应该进行注释,注释必须列出:版本说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释还应有函数功能简要说明
示例(本人的头文件头注释,当然并不局限此格式):
源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
示例(本人源文件头注释,不局限与此格式)
说明:Description一项描述本文件的内容、功能、内容各部分之间的关系及本文件与其他文件关系等。History是修改历史列表,每条记录应包括修改日期、修改人、修改内容简述等。
函数头部进行注释,例出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
示例:(本人的函数头注释,不局限与此格式)
我们应该养成边写代码边注释的习惯,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除
注释内容要清楚、明了、含义准确、防止注释二义性。
说明:错误的注释不但无益反而有害
避免在代码中使用缩写,特别是非常用的缩写
说明:在使用缩写时或之前,应对缩写进行必要的说明。
注释应与其描述的代码相近,对代码的注释应放在上方(对代码块的注释)或右方(对单条语句的注释),相邻位置,不可放在下面,如放在上方则需要与其上面的代码用空行隔开
例如:
2
3
4
5
6
7
1
2
3
4
5
6
7
对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时必须加以注释,说明其物理含义。变量、常量、宏的注释应该放在其上方或右方
示例:
2
1
2
数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应该放在其上方相邻位置,不可放在下面,对结构的每个域的注释要放在此域的右方
示例:
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8
全局变量要有详细的注释,抱括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等等
示例:
2
3
4
5
6
7
8
9
10
1
2
3
4
5
6
7
8
9
10
注释与所描述的内容进行同样的缩排,并且将注释与其上面的代码用空行分隔
说明:可使程序排版整齐,并方便注释的阅读与理解
示例:
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8
对变量的定义和分支语句(条件分支、循环语句等)必须编写注释
说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档
对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完后,下一个语句前加上明确的注释。
说明:这样比较清楚程序编写者的意图,有效防止无故遗漏break语句
示例
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
除非必要,请不要在一行代码的中间插入注释,否则会让程序的可读性降低
通过对函数或过程、变量、结构等正确的命名以合理的组织代码的结构,使代码成为自注释的
在代码的功能、意图层次上进行注释,提供有用的,额外的信息
说明:注释的目的是解释代码的目的,功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没有必要的重复注释信息。
示例:
2
3
1
2
3
在代码块的结束行右方加注释标记,以表明某程序块结束
说明:当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读
示例:
2
3
4
5
6
7
8
9
1
2
3
4
5
6
7
8
9
注释格式尽量统一,建议使用 /* …… */
注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能够用非常流利准确的英文表达
说明:注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文
代码规范这一点就不用多说了,写程序一定要有规范,否则你会被别人说你的程序像狗屎一样难看。而且读起来简直头疼到爆炸。这里我就小小的展示一下我的代码规范,一般大家都有自己的习惯,也应该养成这样的好习惯。这样不仅会为你的面试工作加分,而且可以提高你的开发效率。
以上的代码格式是博主自己养成的编码习惯,还算是标准,仅供大家参考,每个人都有每个人的习惯,但是有习惯总比没有习惯随便写的好!!
也许有人会这样问。但是我只想说如果你还在这样问,那么你不仅不是一个优秀的程序员,应该说你是不是程序员都应该受到质疑。
先说一下注释的重要性:
在公司的开发中,我们要明白程序不是写给自己看的,也不是所有的代码都是自己写的,我们不仅需要看别人的代码而且还要把自己的代码交给别人看,团队看。也许还会在你离职以后交给你的接班人看。而且,就算是你写的程序,如果过了很久你再去看的话(相信也会受到一万点真实伤害,脱口而出”这是哪个家伙写的这是什么东西!!!”)所以,程序文档的书写,注释的书写,以及标准的编码规范就非常的重要。(而这些是每一个大学老师都不会交给你的)
一般情况下,源程序的有效注释量必须在20%以上。
说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加上,注释不宜太多。也不能太少。注释语言必须准确、易懂、简洁
说明性文件(如头文件.h文件、inc文件、.def文件、编译说明文件.cfg等)头部应该进行注释,注释必须列出:版本说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释还应有函数功能简要说明
示例(本人的头文件头注释,当然并不局限此格式):
源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
示例(本人源文件头注释,不局限与此格式)
说明:Description一项描述本文件的内容、功能、内容各部分之间的关系及本文件与其他文件关系等。History是修改历史列表,每条记录应包括修改日期、修改人、修改内容简述等。
函数头部进行注释,例出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
示例:(本人的函数头注释,不局限与此格式)
我们应该养成边写代码边注释的习惯,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除
注释内容要清楚、明了、含义准确、防止注释二义性。
说明:错误的注释不但无益反而有害
避免在代码中使用缩写,特别是非常用的缩写
说明:在使用缩写时或之前,应对缩写进行必要的说明。
注释应与其描述的代码相近,对代码的注释应放在上方(对代码块的注释)或右方(对单条语句的注释),相邻位置,不可放在下面,如放在上方则需要与其上面的代码用空行隔开
例如:
//块注释 /* get replicate sub system index and net indicator */ repss_ind = ssn_data[index].repssn_index; repss_ni = ssn_data[index].ni; //单句注释 int num = MAXSIZE; //set num = MAX1
2
3
4
5
6
7
1
2
3
4
5
6
7
对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时必须加以注释,说明其物理含义。变量、常量、宏的注释应该放在其上方或右方
示例:
/* active statistic task number */ #define MAX_ACT_TASK_NUMBER 10001
2
1
2
数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应该放在其上方相邻位置,不可放在下面,对结构的每个域的注释要放在此域的右方
示例:
/* sccp interface with sccp user primitive message name */ enum SCCP_USER_PRIMITIVE { N_UNITDATA_IND,/* sccp notify sccp user uint data */ N_NOTTICE_IND, /* sccp notify user the NO.7 net */ /* transmission this message */ N_UNITDATA_ERQ /* sccp user's unit data transmission */ };1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8
全局变量要有详细的注释,抱括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等等
示例:
/* The ErrorCode when SCCP translate */ /* Global Title failure, as follows */ /* 0 -- SUCCESS 1 -- GT Table error */ /* 2 -- GT error others - no user */ /* only function SCCPTranslate() in */ /* this modual can modlify it, and other */ /* modual can visit it through call */ /* the function GetGTTransErrorCode() */ BYTE g_GTranErrorCode;1
2
3
4
5
6
7
8
9
10
1
2
3
4
5
6
7
8
9
10
注释与所描述的内容进行同样的缩排,并且将注释与其上面的代码用空行分隔
说明:可使程序排版整齐,并方便注释的阅读与理解
示例:
void example_fun(void) { /* Code one comments */ CodeBlock One; /* Code two comments */ CodeBlock Two; }1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8
对变量的定义和分支语句(条件分支、循环语句等)必须编写注释
说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档
对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完后,下一个语句前加上明确的注释。
说明:这样比较清楚程序编写者的意图,有效防止无故遗漏break语句
示例
switch(elect) { num CMB_UP: { pressup(); break; } case CMB_DOWN: { num = pressdown(); if (num > 1) { break; } else { /* not break */ /* now must jump to CMB_MIND */ } } case CMB_MIND: { ... break; } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
除非必要,请不要在一行代码的中间插入注释,否则会让程序的可读性降低
通过对函数或过程、变量、结构等正确的命名以合理的组织代码的结构,使代码成为自注释的
在代码的功能、意图层次上进行注释,提供有用的,额外的信息
说明:注释的目的是解释代码的目的,功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没有必要的重复注释信息。
示例:
//该注释提供了有用的信息 /* if mtp receive a message from links */ if (receive_flag)1
2
3
1
2
3
在代码块的结束行右方加注释标记,以表明某程序块结束
说明:当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读
示例:
if (...) { //progream code while (index < MAX_INDEX) { //progream code; }/*while end */ }/*end of if*/ //指明是哪条if结束1
2
3
4
5
6
7
8
9
1
2
3
4
5
6
7
8
9
注释格式尽量统一,建议使用 /* …… */
注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能够用非常流利准确的英文表达
说明:注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文
代码规范
代码规范这一点就不用多说了,写程序一定要有规范,否则你会被别人说你的程序像狗屎一样难看。而且读起来简直头疼到爆炸。这里我就小小的展示一下我的代码规范,一般大家都有自己的习惯,也应该养成这样的好习惯。这样不仅会为你的面试工作加分,而且可以提高你的开发效率。以上的代码格式是博主自己养成的编码习惯,还算是标准,仅供大家参考,每个人都有每个人的习惯,但是有习惯总比没有习惯随便写的好!!
相关文章推荐
- 手把手教你写_“华为”_的标准注释与文档,以及代码规范
- 【风宇冲】Unity3D教程宝典之 C#代码注释规范及文档生成
- NET中的规范标准注释(二) -- 创建帮助文档入门篇
- 再读华为代码规范文档
- C# 代码注释规范文档
- WEB前端开发规范文档以及如何提高代码编写效率
- php代码注释规范,php文档,phpdoc,phpdocuments
- 华为代码注释标准
- 华为代码规范文档
- C#代码注释规范及文档生成
- Unity3D C#代码注释规范及文档生成
- 【风宇冲】Unity3D教程宝典之 C#代码注释规范及文档生成
- 《从零开始学Swift》学习笔记(Day 57)——Swift编码规范之注释规范:文件注释、文档注释、代码注释、使用地标注释
- 华为软件编程规范和范例 7 —— 代码编辑、编译、审查和代码测试、维护以及宏
- Android生日礼物(含拼图游戏,背景音乐,自动拨号等功能实现)--根据代码规范修改注释以及定义
- C#代码生成XML文档以及规范XSD
- Css代码标准规范-注释
- 《从零开始学Swift》学习笔记(Day 57)——Swift编码规范之注释规范:文件注释、文档注释、代码注释、使用地标注释
- 转载WEB2.0标准XHTML代码规范
- Delphi代码标准文档