《代码注释的13个技巧》由会员分享,可在线阅读,更多相关《代码注释的13个技巧(5页珍藏版)》请在金锄头文库上搜索。
1、以下是如何注释代码的13tips,它们会在日后帮助你更容易理解和维护代码。方法/步骤1. 1Comment each level(每个级别的注释有统一的风格)注释每一个代码块,并且在各个级别的代码块上,要使用统一的注释方法。例如:对于类,应包含简单的描述、作者以及最近的更改日期对于方法,应包含目的的描述、功能、参数以及返回值使用统一的注释规则对于一个团队是非常重要的。当然,更加推荐使用注释的约定和工具(例如,C#的XML或Java的Javadoc),它们会是注释变得更加容易。2. 2Use paragraph comments(对段落注释)将代码块分成若干完成独立功能的“段落”,并在每个“段落
2、”前添加注释,向读者说明“即将发生什么”。/ Check that all data records/ are correctforeach (Record record in records) if (rec.checkStatus()=Status.OK) . . . / Now we begin to perform/ transactionsContext ctx = new ApplicationContext();ctx.BeginTransaction();. . .3. 3Align comments in consecutive lines(对齐注释行)对于拥有后缀式注释的多
3、行代码,排版注释代码,使各行注释对齐到同一列。const MAX_ITEMS = 10; / maximum number of packetsconst MASK = 0x1F; / mask bit TCP一些开发人员使用tab来对齐注释,有些则使用空格。但是由于tab在不同的编辑器或者IDE上会有所不同,最好还是使用空格。4. Dont insult the readers intelligence(不要侮辱读者的智商)不要写没用的注释,例如:if (a = 5) / if a equals 5 counter = 0; / set the counter to zero写这种无用的注释
4、不但浪费你的时间,而且读者在读这种很容易理解的代码时,很容易被你的注释转移注意力,浪费了时间。5. Be polite(要有礼貌)不要写不礼貌的注释代码,例如“注意,愚蠢的使用者输入了一个负数”,或者“修正由于最初的开发者的可怜且愚蠢的编码所造成的副作用”。这样的注释冒犯了作者,而且你并不知道谁会在将来读到这段注释你老板、客户或者是你在注释中冒犯的那个可怜且愚蠢的开发人员。6. Get to the point(简明扼要)不要在注释中写的过多,不要写玩笑、诗和冗长的话。总之,注释需要简单直接。7. Use a consistent style(风格一致)一 些人认为注释应该能让非程序员也能看懂
5、,但是也有些人认为注释仅仅是指导程序员的。不管怎么说,像Successful Strategies for Commenting Code中所说,真正重要的是注释始终面向同一个读者,在这点上,应该保持一致。个人认为,我很怀疑会有非程序人员阅读代码,所以应该把阅读注释的对象 定位为开发人员。8. Use special tags for internal use(在内部使用特殊的标签)团队中处理代码时,在程序员之间应采用一系列统一的标签注释进行交流。例如,很多团队使用“TODO”来表示一段需要额外工作的代码。int Estimate(int x, int y) / TODO: implement
6、 the calculations return 0;标签注释并不解释代码,而是引起主意或者传递信息。但是,使用这种方法时,务必要完成标签注释传递的信息。9. Comment code while writing it(写代码的同时,完成注释)写代码的同时添加注释,因为此时你的思路最为清晰。如果你把注释的任务留到最后,那么你相当于经历了两次编码。“我没有时间注释”“我太忙了”“项目耽误了”这些往往是不写注释的理由。所以,程序员们认为,最理想的解决方法是写代码前先写注释。例如:public void ProcessOrder() / Make sure the products are avai
7、lable / Check that the customer is valid / Send the order to the store / Generate bill10. Write comments as if they were for you (in fact, they are)把代码的读者想象成你自己(实际情况往往如此)注 释代码时,不仅仅要为将来可能维护你代码的人考虑,而且要考虑到读注释的可能是你。伟大的Phil Haack说过:“每当有偶一行代码被敲上屏幕,你都要从维护的角度审视一边这段代码。” As soon as a line of code is laid on t
8、he screen, youre in maintenance mode on that piece of code.(著名的话不敢不附上原句)结果,我们自己往往是我们良好注释的受益者,或者是烂注释的受害人。11. Update comments when you update the code(更新代码时,记得更新注释)如果不能随着代码的更新而更新注释,那么即使再准确的注释也毫无意义。代码和注释必须同步,否则这些注释对于维护你代码的程序人员来说简直是折磨。在使用refactoring工具自动更新代码时,应尤其注意,它们会自动更新代码而不会改变注释,这些注释自然就过期了。12. The gol
9、den rule of comments: readable code(可读性良好的代码是最好的注释)对 于许多程序员来说,基本的原则之一就是:让代码自己说话。有人可能会怀疑这是那些不爱写注释的程序员的借口,然而这确实是一个不争的事实。自我解释良好的 代码对于编码来说大有益处,不但代码容易理解甚至使注释变得没有必要。举例来说,在我的文章Fluid Interfaces中展示了什么是清晰的自我解释型代码:Calculator calc = new Calculator();calc.Set(0);calc.Add(10);calc.Multiply(2);calc.Subtract(4);Con
10、sole.WriteLine( Result: 0, calc.Get() );在 本例中,注释是没必要的,并且会违背tip#4 。为了使代码更加可读,应该考虑使用适当的名字(像在经典的Ottingers Rules描述的),确保正确的缩进和代码风格栏线(代码风格栏线是类似于#region #endregion这类的东西吧?)。如果这一点做的不好,直接后果是,你的注释看起来就像是在为晦涩难懂的代码而道歉。13. Share these tips with your colleagues(与你的同事share这些tips)尽管tip#10中曾说过良好的注释会是自己从中收益,但是这些tips会使所有开发人员收益,尤其是在团队合作的环境中。因此大方的与同事分享这些注释的技巧,让我们都能写出易懂而且好维护的代码。