代码整洁之道
第4章 注释
1、注释是为了弥补代码表达时的失败;
尽量用清楚的代码表达意图,而不是使用注释(虽然注释不可避免),因为程序员不能坚持维护注释;
唯一真正好的注释是你想办法不去写注释;
2、好注释:
(1)法律信息;
----版权信息等;
(2)提供信息的注释、对意图的解释;
----总体注释,函数作用的注释,语句块作用的注释等;
(3)阐释;
----晦涩参数或变量的注释;
(4)警示;
(5)TODO注释;
----程序员认为应该做,但由于某些原因目前还没有做的工作;
3、坏注释:
(1)多余的注释、废话注释;
----没必要仅仅因为需要而写注释;
----代码很清楚的不用写注释;
(2)误导性注释;
----要么不写,要么就写准确;
(3)循规式注释;
----要求每个函数都有javadoc式的注释、每个变量都有注释是愚蠢可笑的;
(4)日志式注释;
----我们现在已经有了功能完备的版本控制工具,不要在每次编辑代码时都加包括日期、作者等信息的add、delete、modify信息;
(5)右括号后面的注释;
----如果你发现由于嵌套太深而需要使用右括号后面的注释,你应该要做的是缩短函数;
(6)确认不要的代码应该删除而不是注释掉;
高质量程序设计指南C++/C语言
第10章 C++/C文件结构和程序版式
10.3.6 注释风格
1、注释只是提示,不必过多,清楚的代码不用注释;
2、修改代码的同时要修改注释,使注释与代码同步,否则错误的注释比没有注释害处更大;
3、注释应当准确、易懂,防止出现二义性。
阅读(362) | 评论(0) | 转发(0) |