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