BYR Achieve · 镜像论坛

声明：这篇文章的原文出自José M. Aguilar的Variable Not Found，这里仅对其进行中文转译工作，一切版权归原作者所有以下将会介绍13给有用的TIPS供你参考注释代码，借此你可以很容易的维护理解你的代码： 1、分级注释对于每一个代码块,每一级代码都进行统一风格的注释，例如： =>对于每一个class，注释应该包含简介，作者，和最后修改日期 =>对于每一个方法，注释应该包含方法的目的，功能，参数，返回值的简介团队工作中统一风格的注释显得格外重要。当然，我们能够接受也推荐使用代码注释工具（例如xml in c#或者javadoc for java)来简化这项任务。 2、段注释我们可以用注释来将代码块分解成多个“段”，每一个段完成一个单一的任务。段注释将会在段起始处说明段内代码的功能，使阅读者明确接下去代码的功能。 // Check that all data records // are correct foreach (Record record in records) { if (rec.checkStatus()==Status.OK) { . . . } } // Now we begin to perform // transactions Context ctx = new ApplicationContext(); ctx.BeginTransaction(); . . . 3、对齐的连行注释对于多行连续代码的尾部注释，将注释对齐将会方便阅读者的阅读 const MAX_ITEMS = 10; // maximum number of packets const MASK = 0x1F; // mask bit TCP 一些程序员习惯用tab来对齐注释，然而其他人却喜欢用空格。因为tab的占位是取决于不同IDE的，而空格则没有这个问题，因此最佳的方法是使用空格。 4、不要侮辱读者的智慧要避免对功能显而易见的代码进行注释，比如： if (a == 5) // if a equals 5 counter = 0; // set the counter to zero 这不仅浪费你的时间去写这些毫无意义的东西，而且这些显然能从代码中推断出的“细节”还扰乱了读者的思路。 5、请礼貌些~ 避免粗鲁的注解，比如“那些愚蠢的家伙输入了个负数”或者“这修正了那些可悲又愚蠢的程序员最初实现的副作用”。这些注释将给作者带来不必要的麻烦，你根本不知道将来谁会来阅读你的代码：你的老板，你的客户，或者是那些你刚侮辱的“可悲”程序员。 6、一针见血请不要写过多的废话来表达你的思想。要避免使用ASCII ART，笑话，诗歌，hyperverbosity（译者注：天哪，谁会去写这些诡异的东西？）。总而言之，保持你注释的简单，明了。 7、统一的风格一些人认为注释的一种作用是让非程序员来读懂代码。而另一些人认为注释仅仅是服务于程序员的。在任何情况下，正犹如Successful Strategies for Commenting Code中所说，最终要的是注释风格要连贯，并且面向统一的阅读者。就我个人而言，我很怀疑那些非程序员会去阅读我们的代码，因此注释应该服务于程序员。 8、为团队服务的特殊标记当我们团队协作时，常会用一些特殊的标记来交流。比如，很多团队用"TODO:"标记来说明这段代码需要补充额外的工作： int Estimate(int x, int y) { // TODO: implement the calculations return 0; } 这些标记并非用来解释代码，而是作为讯息发布的工具。但是，请记住这一点，当你利用这些标记工作时，请确切地理解标记的含义，并且去完成标记隐含的需要你做的工作。 9、边CODE边注释在编写代码的同时完成注释，这有助于你时刻了解自己在干什么。如果你把这项工作放到最后，你不得不痛苦地做第二次的“编码”工作。“我没有时间写注释”，“我很忙”，“项目进度已经晚了”都是我们常用的理由来搪塞注释的编写工作。一些程序员认为应该在CODE前就开始注释的编写，这有助于对程序有一个总体的计划。例如： 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的话来说： ‘当一行代码出现在屏幕上时，你就已经处于维护这行代码的状态下了’（"As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code."）因此，你自己将会是自己那些优秀（糟糕）注释的第一个受益者（受害者）。 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() ); 在这个例子中，注释是没有必要的并且是有悖于TIP 4的。为了写出可阅读的代码，你应该要使用那些合适的变量名，保证正确的缩进，以及采用编码样式指导（coding style guides）。如果没能做到这一点，你就不得不为你那些糟糕的代码负责了~ 13、与你的同事分享这些TIPS 虽然TIP 10说明了我们自己能够从优秀的注释中获益良多，这些TIPS同样有益于你的同事们，特别是与自己一同工作的团队成员。因此，和你的同事们自由得分享这些TIPS，你会发觉代码是多么得容易编写与维护。

13 tips to comment your code~