| 网站首页 | 业界新闻 | 小组 | 威客 | 人才 | 下载频道 | 博客 | 代码贴 | 在线编程 | 编程论坛
欢迎加入我们,一同切磋技术
用户名:   
 
密 码:  
共有 1270 人关注过本帖
标题:今日散分帖,顺便问个程序注释问题。
只看楼主 加入收藏
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
唉,随着c文件越来越多,文件注释问题变得越来越纠结了,象c库函数一样写基本的头,然后再写个html专门写每个函数的用途,返回值简介?

我们都在路上。。。。。
2011-08-19 12:23
TonyDeng
Rank: 20Rank: 20Rank: 20Rank: 20Rank: 20
等 级:贵宾
威 望:304
帖 子:25859
专家分:48889
注 册:2011-6-22
收藏
得分:0 
6楼的注释不错了,只是尚欠清晰。如果程序不是很简单,则纯注释某一行的作用不大。你已经将相对集中的功能段用空行分隔,那么可以注释这个段干什么的,而不用注释具体行和语句,因为那很可能要改的(可能是代码出错或别的补充原因),但段的意图是不会变的,阅读者根据注释检查代码是否实现意图即可,而不是根据代码猜测意图。

接口处的注释,是给调用者看的,因为那是头文件,对外公开,重点是如何使用。在实现代码文件,重点才是如何实现。这点你基本做到了。
收到的鲜花
  • hellovfp2011-08-19 12:41 送鲜花  10朵   附言:很好的建议,谢谢

授人以渔,不授人以鱼。
2011-08-19 12:35
lz1091914999
Rank: 14Rank: 14Rank: 14Rank: 14
来 自:四川
等 级:贵宾
威 望:37
帖 子:2011
专家分:5959
注 册:2010-11-1
收藏
得分:11 
果断接分。

My life is brilliant
2011-08-19 12:36
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
以下是引用TonyDeng在2011-8-19 12:35:33的发言:

6楼的注释不错了,只是尚欠清晰。如果程序不是很简单,则纯注释某一行的作用不大。你已经将相对集中的功能段用空行分隔,那么可以注释这个段干什么的,而不用注释具体行和语句,因为那很可能要改的(可能是代码出错或别的补充原因),但段的意图是不会变的,阅读者根据注释检查代码是否实现意图即可,而不是根据代码猜测意图。

接口处的注释,是给调用者看的,因为那是头文件,对外公开,重点是如何使用。在实现代码文件,重点才是如何实现。这点你基本做到了。
有道理,注释一下大段的意图,免得日后对整个功能的流程意图阅读再回想!感谢Tong大侠的指导,偶再改改。

我们都在路上。。。。。
2011-08-19 12:41
QQ346957135
Rank: 7Rank: 7Rank: 7
等 级:黑侠
帖 子:148
专家分:658
注 册:2011-8-9
收藏
得分:11 
个人认为注释跟阅读对象有关,本人写程序只标清函数体功能及算法的关键点。如果是为初学者写程序,当然是越详细越好。

A real warrior never quits.
2011-08-19 12:55
zhoufeng1988
Rank: 15Rank: 15Rank: 15Rank: 15Rank: 15
来 自:北京
等 级:贵宾
威 望:27
帖 子:1432
专家分:6329
注 册:2009-5-31
收藏
得分:11 
又见楼主了。

之前的过激言辞希望楼主不要介意,顺便也表示歉意。
看到你的帖子,我也说两句吧。

实际上注释规范是有很多的。也是分行业的。
国内军工,例如一些航空、航天、中电集团、船舶等很多单位要求要符合GJB5369的标准。所以有一套GJB5369的编码标准,这些编码标准里面有针对C注释的。
国际上有名的还有MISRA C等。
这些标准相对比较严格,不过也是一种很好的规范。

还有一些较大的单位,也有自己的编码标准。华为就有一些。也可以参照他们的规范来编码。
2011-08-19 13:13
zhoufeng1988
Rank: 15Rank: 15Rank: 15Rank: 15Rank: 15
来 自:北京
等 级:贵宾
威 望:27
帖 子:1432
专家分:6329
注 册:2009-5-31
收藏
得分:0 
编码规范 [CODSTA]
开关('switch')语句的所有 'case' 和 'default' 标签应该有一个显式的 'break' 或 'return' 语句, 或者 'fall through'(落空) 注释 [CODSTA-56-3]

注释 [COMMENT]
对每一个文件进行注释 [COMMENT-03-3]
注释每个函数 [COMMENT-04-3]
每一个变量声明都应该进行注释 [COMMENT-05-3]
每一个类型定义(typedef)都应该进行注释 [COMMENT-06-3]
每一个枚举值都应该进行注释 [COMMENT-07-3]
每一个结构成员变量都应该进行注释 [COMMENT-08-3]
所有汇编程序的使用应该被注释说明 [COMMENT-09-3]
使用浮点运算应该被注释说明 [COMMENT-10-3]

中华人民共和国国家军用标准 [GJB5369]
禁止使用嵌套的注释 [GJB5369-4_10_1_1-3]
建议不使用单行注释“∥” [GJB5369-4_10_2_2-5]
使用的八进制数必须加以注释 [GJB5369-4_8_1_3-3]

联合攻击战斗机 [JSF]
无法被编译的代码段落不能被“注释掉” [JSF-127-2]
每一个变量声明都应该进行注释 [JSF-132_a-3]
每一个类型定义(typedef)都应该进行注释 [JSF-132_b-3]
每一个枚举值都应该进行注释 [JSF-132_c-3]
每一个结构成员变量都应该进行注释 [JSF-132_d-3]
对每一个文件进行注释 [JSF-133_a-3]
注释每个函数 [JSF-134-4]
整数除法操作语句之前必须有注释 [JSF-167-2]
度量指标 [METRICS]
模块中注释行所占比例应该为20到60 [METRICS-19-3]
函数前面和内部的注释模块的数量与函数内语句的数量之比应该 > 0.2 [METRICS-41-3]

MISRA C [MISRA]
整数除法操作语句之前必须有注释 [MISRA-041-5]

MISRA C 2004 [MISRA2004]
空语句只允许单独存在一行或可能在其后面跟着注释 [MISRA2004-14_3-3]
#include 之前只允许有预处理命令和注释 [MISRA2004-19_1-3]
源代码只能使用 /* ... */ 来注释 [MISRA2004-2_2-3]
禁止使用嵌套注释 /* [MISRA2004-2_3-3]
无法被编译的代码段落不能被“注释掉” [MISRA2004-2_4-4]
2011-08-19 13:22
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 15楼 QQ346957135
唉,先前偶也这样想过,不过后来吃了亏,n早以前写的代码,回头来读,结果自己都搞不清楚了。
总算明白程序不只是自己读的,别人也要读,所以现在苦练注释。

我们都在路上。。。。。
2011-08-19 13:27
wjm22
Rank: 3Rank: 3
等 级:论坛游侠
帖 子:44
专家分:118
注 册:2011-7-5
收藏
得分:11 
只要让别人看的冻,都可以
2011-08-19 13:27
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 16楼 zhoufeng1988
呵呵,受教了,偶再仔细的阅读一下代码注释规范,选一种做为自己的终身标准吧。以后有很多的问题还向周版主请教,还望到时不吝赐教。学习求进步,相比于昨天的我,今天比昨天好,就是进步。

我们都在路上。。。。。
2011-08-19 13:35
快速回复:今日散分帖,顺便问个程序注释问题。
数据加载中...
 
   



关于我们 | 广告合作 | 编程中国 | 清除Cookies | TOP | 手机版

编程中国 版权所有,并保留所有权利。
Powered by Discuz, Processed in 0.091182 second(s), 8 queries.
Copyright©2004-2024, BCCN.NET, All Rights Reserved