On Code Comment
来源:互联网 发布:矢量数据的编码方式 编辑:程序博客网 时间:2024/05/01 01:44
Brian W. Kernighan and Rob Pike have some excellent suggestions for writing comments. They are said best as they appear in "The Practice of Programming," [1]:
- Don't belabor the obvious. Comments shouldn't report self-evident information such as the fact that
i++
has incrementedi
. - Don't comment bad code, rewrite it. Comment anything unusual or potentially confusing, but when the comment outweighs the code, the code probably needs fixing.
- Don't contradict the code. Most comments agree with the code when they are written, but as bugs are fixed and the program evolves, the comments are often left in their original form, resulting in disagreement with the code. Whatever the source of disagreement, a comment that contradicts the code is confusing, and many a debugging session has been needlessly protracted because a mistaken comment was taken as truth. When you change code, make sure that the comments are still accurate. Comments should not only agree with code, they should support it.
- Clarify, don't confuse. Comments are supposed to help readers over the hard parts, not create more obstacles.
- When it takes more than a few words to explain what's happening, it's often an indication that code should be rewritten.
- Students are taught that it's important to comment everything. Professional programmers are often required to comment all their code. But the purpose of commenting can be lost in blindly following rules. Comments are meant to help a reader understand parts of the program that are not readily understood from the code itself. As much as possible, write code that is easy to understand; the better you do this, the fewer comments you need. Good code needs fewer comments than bad code.
References
[1] Kernighan, Brian W. and Pike, Rob, The Practice of Programming, Addison Wesley, 1999, pages 23-27.
- On Code Comment
- Code Sytle comment
- Art of code comment
- comment on的重要意义
- comment on google play
- A Comment on Comments
- Read & Comment Android Source Code
- oracle comment on的用法
- oracle comment on的用法
- Oracle comment on的用法
- Oracle comment on的用法
- Oracle comment on的用法
- oracle comment on的用法
- 07-Oracle中的Comment on
- oracle comment on的用法
- POWER DESIGNER COMMENT CODE 自动填充
- Comment Only What the Code Cannot Say
- Comment Only What the Code Cannot Say
- 不注册调用ActiveX Dll
- Windows所有版本里最常见的一些进程
- vc 快捷键
- 经历了几次改革后,明白了在中国生存下去的法则
- 终于在同事的帮助下解决了IE主页被修改为PKPKPK.net并弹出广告的问题
- On Code Comment
- ucos资料
- 结构体对齐的具体含义
- 取得SQLServer字段的描述内容
- Zend认证模拟题(部分)
- 用于持久对象的本地查询 - 克服基于字符API的缺陷(译)
- PHP环境配置
- mldonkey——Linux下的电驴
- 狗的分类