十三个代码注释的小技巧

大家好，欢迎来到IT知识分享网。1. 对不同级别的代码进行注释

对于不同级别的代码块，要使用统一的方法来进行注释。例如：

对于每一个类，需要包含一段简明扼要的描述，作者和上一次修改的时间

对于每一个方法，需要包含这个方法的用途，功能，参数以及返回结果

当你在一个团队里面的时候，采用一套注释的标准是非常重要的。当然，使用一种大家都认可的注释约定和工具（例如C#的XML注释和Java的Javadoc）在一定程度上能推动这项任务。

2. 使用段落注释
首先把代码块分解成多个“段落”，每一个段落都执行单一的任务；然后在每一个“段落”开始之前添加注释，告诉阅读代码的人接下来的这段代码是干什么用的
复制内容到剪贴板
代码:

// 检查所有记录都是正确的 foreach (Record record in records) { if (rec.checkStatus()==Status.OK) { . . . } } // 现在开始进行处理 Context ctx = new ApplicationContext(); ctx.BeginTransaction(); . . .

const MAX_ITEMS = 10; // maximum number of packets const MASK = 0x1F; // mask bit TCP 

有些开发人员使用tab来对齐注释，而另外一些人会用空格来对齐。由于tab在不同的编辑器和集成开发环境中会有所不同，所以最佳的方法是使用空格来对齐注释行。

4. 不要侮辱阅读者的智慧

要避免没用的注释，代码:

if (a == 5) //如果a等于5 counter = 0 //把counte设为0 

这不单把时间浪费在写没用的注释上面，同时也在分散读者的注意力。

8. 在内部使用特殊的标签
当你在一个团队里工作的时候，采用一组一致的标签能帮助不同的程序员沟通。例如，很多团队会采用“TODO”标签来表示一段尚未完成的代码
复制内容到剪贴板
代码:

int Estimate(int x, int y) { // TODO: implement the calculations return 0; }

标签注释并不会解释代码，它们寻求注意或者是传递信息。但是如果适当地使用这种技术，要记住跟进这段代码并且完成该标签传递的任务。

9. 在写代码的同时添加注释
当你在写代码而且记忆犹新的同时就添加注释。如果等到项目后期才添加注释，会让你事倍功半。“我没有时间写注释”，“我的时间很紧迫”和“项目已经延迟了”，这些都是不写注释的常见借口。有些工程师觉最佳的解决方法是“注释先行”。例如：
复制内容到剪贴板
代码:

public void ProcessOrder() { // Make sure the products are available // Check that the customer is valid // Send the order to the store // Generate bill }

10. 把自己想象为注释的读者（事实上就是如此）
当你正在给代码写注释的时候，不仅仅为日后维护你的代码的开发者考虑，同时也设想一下如果自己就是注释的读者。Phil Haack曾经说过：
“一旦一行代码被敲到文件中, 你就已经要开始维护那一行代码了。”
所以，我们自己就是好（或者坏）注释的第一个受益者（或者受害者）。

11. 更新代码的时候要更新注释

如果注释没有随着代码的修改而更新，那么这些注释将是毫无意义的。代码和注释需要同步，否则注释只会让维护代码的开发者更加痛苦。需要特别注意的是，一些重构的工具会自动更新代码，但是却没有自动更新注释，那么注释就自然而然地过期作废了。

12. 良好可读性代码是注释的金科玉律
对于很多开发者来说，一个基本的原则就是：让代码自己描述自己。虽然有人怀疑这是由不喜欢写注释的程序员所倡导的一场运动，但是无需解释的代码有很大的好处，这些代码更加容易理解甚至让注释变得没有必要。例如，在我的文章Fluid Interfaces中就给大家展示了什么是清晰的无需解释的代码。
复制内容到剪贴板
代码:

Calculator calc = new Calculator(); calc.Set(0); calc.Add(10); calc.Multiply(2); calc.Subtract(4); Console.WriteLine( “Result: {0}”, calc.Get() ); 

在这个例子里面，注释就像是违反了第4条技巧那样，变得毫无必要。要写出可读性好的代码，你需要使用适当的命名方式（在经典的Ottinger’s Rules中有阐述），保证恰当的缩进，并且采用编码风格指导。如果代码不遵守这条技巧，那么注释看起来就好像是为自己不好的代码的写道歉信一样。