Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
热情的rhew
Ohos 1.0 With Comments
提交
c079ac4f
O
Ohos 1.0 With Comments
项目概览
热情的rhew
/
Ohos 1.0 With Comments
通知
3
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
O
Ohos 1.0 With Comments
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
前往新版Gitcode,体验更适合开发者的 AI 搜索 >>
提交
c079ac4f
编写于
9月 30, 2020
作者:
H
Harmonica
提交者:
Gitee
9月 30, 2020
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
update 注释编写规范.txt.
上级
084947e8
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
19 addition
and
19 deletion
+19
-19
注释编写规范.txt
注释编写规范.txt
+19
-19
未找到文件。
注释编写规范.txt
浏览文件 @
c079ac4f
...
...
@@ -2,10 +2,10 @@
说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
1、说明性文件(如头文件.h 文件、.inc 文件、.def 文件、编译说明文件.cfg 等)头部应进行注释,如源代码中已有注释,不需要重新添加,应保留原有的信息,包括但不限于:版权说明、版本号、生成日期、作者等
####
1、说明性文件(如头文件.h 文件、.inc 文件、.def 文件、编译说明文件.cfg 等)头部应进行注释,如源代码中已有注释,不需要重新添加,应保留原有的信息,包括但不限于:版权说明、版本号、生成日期、作者等
2、函数头部应进行注释,列出:函数的目的/ 功能、输入参数、输出参数、返回值、调用关系(函数、表)等
####
2、函数头部应进行注释,列出:函数的目的/ 功能、输入参数、输出参数、返回值、调用关系(函数、表)等
示例:
...
...
@@ -37,11 +37,11 @@
3、注释的内容要清楚、明了,含义准确,防止注释二义性。错误的注释不但无益反而有害。
####
3、注释的内容要清楚、明了,含义准确,防止注释二义性。错误的注释不但无益反而有害。
4、避免在注释中使用缩写,特别是非常用缩写。在使用缩写时或之前,应对缩写进行必要的说明。
####
4、避免在注释中使用缩写,特别是非常用缩写。在使用缩写时或之前,应对缩写进行必要的说明。
5、注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开
####
5、注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开
示例:如下例子不符合规范。
...
...
@@ -85,7 +85,7 @@ repssn_ni = ssn_data[index].ni;
6、对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方
####
6、对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释,说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方
示例:
...
...
@@ -100,7 +100,7 @@ repssn_ni = ssn_data[index].ni;
7、数据结构声明( 包括数组、结构、类、枚举等) ,如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方
####
7、数据结构声明( 包括数组、结构、类、枚举等) ,如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方
示例:可按如下形式说明枚举/数据/联合结构。
...
...
@@ -126,7 +126,7 @@ enum SCCP_USER_PRIMITIVE
8、全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明
####
8、全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明
示例:
...
...
@@ -152,7 +152,7 @@ BYTE g_GTTranErrorCode;
9、注释与所描述内容进行同样的缩排
####
9、注释与所描述内容进行同样的缩排
说明:可使程序排版整齐,并方便注释的阅读与理解。
...
...
@@ -196,7 +196,7 @@ void example_fun( void )
}
10、将注释与其上面的代码用空行隔开
####
10、将注释与其上面的代码用空行隔开
示例:如下例子,显得代码过于紧凑。
...
...
@@ -224,13 +224,13 @@ program code two
11、对变量的定义和分支语句(条件分支、循环语句等)必须编写注释
####
11、对变量的定义和分支语句(条件分支、循环语句等)必须编写注释
说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。
12、对于switch 语句下的case 语句,如果因为特殊情况需要处理完一个case 后进入下一个case 处理,必须在该case 语句处理完、下一个case 语句前加上明确的注释
####
12、对于switch 语句下的case 语句,如果因为特殊情况需要处理完一个case 后进入下一个case 处理,必须在该case 语句处理完、下一个case 语句前加上明确的注释
说明:这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。
...
...
@@ -296,19 +296,19 @@ case CMD_D:
...
13、避免在一行代码或表达式的中间插入注释
####
13、避免在一行代码或表达式的中间插入注释
说明:除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
14、通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的
####
14、通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的
说明:清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
15、在代码的功能、意图层次上进行注释,提供有用、额外的信息
####
15、在代码的功能、意图层次上进行注释,提供有用、额外的信息
说明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
...
...
@@ -332,7 +332,7 @@ if (receive_flag)
16、在程序块的结束行右方加注释标记,以表明某程序块的结束
####
16、在程序块的结束行右方加注释标记,以表明某程序块的结束
...
...
@@ -370,7 +370,7 @@ if (...)
17、注释格式尽量统一,除了在一行代码尾部进行注释的情况,统一使用“/* …… */”
####
17、注释格式尽量统一,除了在一行代码尾部进行注释的情况,统一使用“/* …… */”
18、注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达
\ No newline at end of file
#### 18、注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达
\ No newline at end of file
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录