代码注释的13个技巧

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

1、以下是如何注释代码的13tips，它们会在日后帮助你更容易理解和维护代码。方法/步骤1.1Commenteachlevel（每个级别的注释有统一的风格）注释每一个代码块，并且在各个级别的代码块上，要使用统一的注释方法。例如：对于类，应包含简单的描述、作者以及最近的更改日期对于方法，应包含目的的描述、功能、参数以及返回值使用统一的注释规则对于一个团队是非常重要的。当然，更加推荐使用注释的约定和工具（例如，C#的XML或Java的Javadoc），它们会是注释变得更加容易。2.2Useparagraphcomments（对段落注释）将代码块分成若干完成独立功能的“段落”，并

2、在每个“段落”前添加注释，向读者说明“即将发生什么”。//Checkthatalldatarecords//arecorrect foreach(Recordrecordinrecords) {  if(rec.checkStatus()==Status.OK)  {     ...   } } //Nowwebegintoperform //transactions Contextctx=newApplicationContext(); ctx.BeginTransaction();...1.3Aligncommentsinconsecutivelines（对齐注释行

3、）对于拥有后缀式注释的多行代码，排版注释代码，使各行注释对齐到同一列。constMAX_ITEMS=10;//maximumnumberofpackets constMASK=0x1F;  //maskbitTCP一些开发人员使用tab来对齐注释，有些则使用空格。但是由于tab在不同的编辑器或者IDE上会有所不同，最好还是使用空格。2.Don'tinsultthereader'sintelligence（不要侮辱读者的智商）不要写没用的注释，例如：if(a==5)   //ifaequals5   counter=0;//setthecountertozero写这种无用

4、的注释不但浪费你的时间，而且读者在读这种很容易理解的代码时，很容易被你的注释转移注意力，浪费了时间。3.Bepolite（要有礼貌）不要写不礼貌的注释代码，例如“注意，愚蠢的使用者输入了一个负数”，或者“修正由于最初的开发者的可怜且愚蠢的编码所造成的副作用”。这样的注释冒犯了作者，而且你并不知道谁会在将来读到这段注释——你老板、客户或者是你在注释中冒犯的那个可怜且愚蠢的开发人员。4.Gettothepoint（简明扼要）不要在注释中写的过多，不要写玩笑、诗和冗长的话。总之，注释需要简单直接。5.Useaconsistentstyle（风格一致）一些人认为注释应该能让非程

5、序员也能看懂，但是也有些人认为注释仅仅是指导程序员的。不管怎么说，像《SuccessfulStrategiesforCommentingCode》中所说，真正重要的是注释始终面向同一个读者，在这点上，应该保持一致。个人认为，我很怀疑会有非程序人员阅读代码，所以应该把阅读注释的对象定位为开发人员。1.Usespecialtagsforinternaluse（在内部使用特殊的标签）团队中处理代码时，在程序员之间应采用一系列统一的‘标签注释’进行交流。例如，很多团队使用“TODO”来表示一段需要额外工作的代码。intEstimate(intx,inty) {  //TODO:

6、implementthecalculations   return0;} ‘标签注释’并不解释代码，而是引起主意或者传递信息。但是，使用这种方法时，务必要完成‘标签注释’传递的信息。2.Commentcodewhilewritingit（写代码的同时，完成注释）写代码的同时添加注释，因为此时你的思路最为清晰。如果你把注释的任务留到最后，那么你相当于经历了两次编码。“我没有时间注释”“我太忙了”“项目耽误了”这些往往是不写注释的理由。所以，程序员们认为，最理想的解决方法是‘写代码前先写注释’。例如：publicvoidProcessOrder() {  //Makesur

7、etheproductsareavailable  //Checkthatthecustomerisvalid   //Sendtheordertothestore   //Generatebill }1.Writecommentsasiftheywereforyou(infact,theyare)把代码的读者想象成你自己（实际情况往往如此）注释代码时，不仅仅要为将来可能维护你代码的人考虑，而且要考虑到读注释的可能是你。伟大的PhilHaack说过：“每当有偶一行代码被敲上屏幕，你都要从维护的角度审视一边这段代码。”"Assoonasal