高效注释代码技巧

《高效注释代码技巧》由会员上传分享，免费在线阅读，更多相关内容在行业资料-天天文库。

1、代码注释的13个技巧博客分类： ·JavaBasic编程工作IDE作者：JoséM.Aguilar（西班牙语）英文译者：TimmMartin中文译者：numenzq 下面的13个技巧向你展示如何添加代码注释，这些技巧都很容易理解和记忆。1.逐层注释为每个代码块添加注释，并在每一层使用统一的注释方法和风格。例如：·针对每个类：包括摘要信息、作者信息、以及最近修改日期等·针对每个方法：包括用途、功能、参数和返回值等在团队工作中，采用标准化的注释尤为重要。当然，使用注释规范和工具（例如C#里的XML，Java里的Ja

2、vadoc）可以更好的推动注释工作完成得更好。2.使用分段注释如果有多个代码块，而每个代码块完成一个单一任务，则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下：//Checkthatalldatarecords//arecorrect foreach(Recordrecordinrecords) {    if(rec.checkStatus()==Status.OK)    {         ...     } } //Nowwebegintoperform //transactions C

3、ontextctx=newApplicationContext(); ctx.BeginTransaction();...3.在代码行后添加注释如果多行代码的每行都要添加注释，则在每行代码后添加该行的注释，这将很容易理解。例如：constMAX_ITEMS=10;//maximumnumberofpackets constMASK=0x1F;   //maskbitTCP在分隔代码和注释时，有的开发者使用tab键，而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致，因此最好的方法还是使

4、用空格键。4.不要侮辱读者的智慧避免以下显而易见的注释：if(a==5)      //ifaequals5     counter=0;//setthecountertozero写这些无用的注释会浪费你的时间，并将转移读者对该代码细节的理解。5.礼貌点避免粗鲁的注释，如：“注意，愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣，你也永远不知道谁将会阅读这些注释，可能是：你的老板，客户，或者是你刚才侮辱过的无能开发者。6.关注要点不要写过多的

5、需要转意且不易理解的注释。避免ASCII艺术，搞笑，诗情画意，hyperverbosity的注释。简而言之，保持注释简单直接。7.使用一致的注释风格一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何，SuccessfulStrategiesforCommentingCode已经规定和阐述了注释的一致性和针对的读者。就个人而言，我怀疑大部分非编程人员将会去阅读代码，因此注释应该是针对其他的开发者而言。8.使用特有的标签在一个团队工作中工作时，为了便于与其它程序员

6、沟通，应该采用一致的标签集进行注释。例如，在很多团队中用TODO标签表示该代码段还需要额外的工作。intEstimate(intx,inty) {    //TODO:implementthecalculations     return0;}注释标签切忌不要用于解释代码，它只是引起注意或传递信息。如果你使用这个技巧，记得追踪并确认这些信息所表示的是什么。9.在代码时添加注释在写代码时就添加注释，这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释，它将多花费你一倍的时间。而“我没有时间写注释”，“我

7、很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该writecommentsbeforecode，用于理清头绪。例如：publicvoidProcessOrder(){   //Makesuretheproductsareavailable   //Checkthatthecustomerisvalid    //Sendtheordertothestore    //Generatebill }10.为自己注释代码当注释代码时，要考虑到不仅将来维护你代码的开发人员要看，而且你自己也可能要

8、看。用PhilHaack大师的话来说就是：“一旦一行代码显示屏幕上，你也就成了这段代码的维护者”。因此，对于我们写得好（差）的注释而言，我们将是第一个受益者（受害者）。11.同时更新代码和注释 如果注释没有跟随代码的变化而变化，及时是正确的注释也没有用。代码和注释应该同步变化，否则这样的注释将对维护你代码的开发者带来更大的困难。使用重构工具时应特别注意，它只会自动更新代码而不会修改注释