代码注释本身就能透露出许多的信息，代码维护记录、开发工具、开发者的联系信息甚至其个人品好。有过就是因为代码注释造成公司信息泄露，导致公司受损的案例。
1、逐层注释
使用统一格式对每一个语句块进行注释，如：
* 类：简单描述、作者、后面修改时间等
* 方法：关于该方法的目的、函数、参数、返回值的描述
在团队工作中，使用统一的注释规范显得尤为重要。当然，也推荐使用一些专门用来添加代码注释的工具，如C#中的XML、Java中的Javadoc等。
2、使用段落型注释
将代码分割成能完成独立任务的段落，并在其前后添加注释，告诉读者程序将要做什么。
|
1
2
3
4
5
6
7
8
9
10
11
12
|
// 检查所有的记录是否正确 foreach (Record record in records) { if (rec.checkStatus()==Status.OK) { . . . } } // 现在开始进行事务处理 Context ctx = new ApplicationContext(); ctx.BeginTransaction(); . . . |
3、对齐连续的行注释
若对多行添加行末注释，应将注释进行对齐，以便于阅读。
|
1
2
|
const MAX_ITEMS = 10; // 数据包的很大数量 const MASK = 0x1F; // TCP标志位 |
有些程序远使用制表符来进行对齐，有些则使用空格。建议使用空格来对齐，因为不同的代码编辑器对制表符的处理会不一样。
4、不要侮辱读者的智商
不要用这样的注释：
|
1
2
|
if (a == 5) // 如果a等于5 counter = 0; // 就将counter的值赋为0 |
这样做只会浪费你的时间，而且读者的注意力会被从代码中转移。
5、注意礼貌
避免使用无礼的注释，如：注意有些蠢蛋会输入一个负数；这修复了程序最初版本遇到的问题，那个无个救药的笨蛋。这样的注释会反映作者的素质，而且你不知道将来谁会读到你的程序：你的老板、顾客，或者是你刚才辱骂过的那个程序员。
6、讲重点
不要在写冗余的注释，也不要用所谓的字符艺术、玩笑、小诗等。总之要保持注释的简单和直接。
7、坚持统一风格
有些人认为代码注释应该简单到让不会编程的人也能看懂，另一些人则认为代码注释只要让程序员看懂就可以了。不管怎样，正如《撰写代码注释的成功策略》中所提到的，代码注释的风格应该是固定的，是为同一个观众准备的。而且我个人认为不太会有非程序员来阅读代码，所以代码注释应该只是针对其他程序员的。
8、使用内部统一规定的标签
在进行团队开发时，可以在注释中使用一些特殊的标签。比如在一些团队中使用“TODO:“标签来表示这里还需要完成其他的一些任务。
|
1
2
3
4
5
|
int Estimate(int x, int y) { // TODO: 实现这项计算 return 0; } |
这里所使用的标签注释并不是用来解释代码，而是引起读者注意并传递一些信息。如果你的团队确实在使用这类注释，就要保证会依此进行作业。
9、边写代码边注释
在写代码的时候，乘脑中记忆还清晰，及时写上注释。如果你想在程序编写完之后再添加注释，也许就会花费你两倍的时间。“我没有时间添加注释”、“我很忙”、“这个项目已经有所拖延了”都将会是你的借口。有些程序员认为你应该在编写代码之前就写好注释，以为你的终终方案作出计划。如：
|
1
2
3
4
5
6
7
|
public void ProcessOrder() { // 保证这些产品是可以购买得到的 // 检查用户时候合法 // 向商店发出订单 // 生成账单 } |
10、就当是为自己写注释（事实上的确是让你自己看的）
在添加代码注释时，要想到这些注释不仅是为将来维护代码的程序员而写，也是为你自己而写。用伟大的Phil Haack的话来说：“当一行代码写好并出现在屏幕上时，你就变成了一名维护人员。”所以，我们自己将会成为代码注释的第一个受益人或受害者。
11、新新代码时同时新新注释
如果注释不随着代码的改变而修改，那在准备的注释也是没有用的。代码和注释应该始终保持同步，否则这些文不对题的注视将使维护人员摸不着头脑。对于那些自动添加注释的工具要格外注意，不要让它忽略新新注释。
12、黄金准则：写可读的代码
有一条基本准备叫“让代码解释它自己”。虽然有人认为这个倡议是由一个懒得写注释的程序提出的，但不可否认的是一条可以自我解释的代码可以让其变得更为易懂，并让注释显得不那么重要。如，在我的Fluid Interfaces文章中有一些可以自我解释的代码的例子：
|
1
2
3
4
5
6
|
Calculator calc = new Calculator(); calc.Set(0); calc.Add(10); calc.Multiply(2); calc.Subtract(4); Console.WriteLine( “Result: {0}”, calc.Get() ); |
在这个例子中，代码不需要注释，否则会违反本文的第四条贴士。要写出可读的代码，你应该考虑使用恰当的名称（在Ottinger’s Rules中有所叙述），确保标识正确，并根据代码规范来撰写。如果没有遵循此条建议，注释可能会被看作是代码的一种“道歉”。
13、和你的同事分享这些贴士
虽然第10条贴士说我们自己将是代码注释的第一个受益者，但如果把这些贴士分享给你的同事，尤其是在同一个团队中工作的同事，你就会发现你们写出的代码注释会更为易懂和易于维护。
|
评论加载中...
|
Copyright@ 2011-2017 版权所有：大连仟亿科技有限公司 辽ICP备11013762-1号 google网站地图 百度网站地图 网站地图
公司地址：大连市沙河口区中山路692号辰熙星海国际2215 客服电话：0411-39943997 QQ：2088827823 42286563
法律声明：未经许可，任何模仿本站模板、转载本站内容等行为者，本站保留追究其法律责任的权利！ 隐私权政策声明
