IT人士的职业规范——注释


这两天将系统敲完了，该整体调试了，调试的过程中，发现了一个很大的问题，就是自己的注释写的不够，有时候不明白U层这个事件是做什么的，有时候不知道这个事件传递的是什么参数，有时候不知道对应的B层和D层是哪个，对应的B和D各做了什么工作，………….所以有的时候就需要自己从头到尾在看一遍代码，看一下传递了什么参数，看这些参数，是做什么用的，看一下，相应的B层对返回的数据做了什么处理，看一下相应的D层，起了什么作用。

这个时候这个过程真的很浪费时间，让自己有一种很厌烦的感觉。这是自己的代码，自己编写，自己调试，就有这样的感觉了，如果让你去调试别人的这样的代码，那别人又该有什么样的感觉那？？是不是要吐了啊？？
所以说在这个小程序中我是深深的体会到了代码注释的重要性。

想了一下当时自己为什么没有编写注释，结合以前米老师讲的课。整理了一下。

①写注释太费时间。

实际上，在编写代码时加上注释根本不需要多少时间。当时是趁热打铁，对于那些代码理解比较通透，写一句注释就是敲那几个字的时间。但是如果后来在添加注释，就不仅仅要敲那几个字，还要在从新理解一下这一块的代码，甚至相关的代码。如果后来不谢注释，那么等到调试的时候就会像上面说的一样了啊。

②有些过程很难注释。

通常而言，如果代码的一个部分很难注释，那么如果没有注释，其他人就更难理解你的代码。自己理解不清楚，怎么会使别人也理解清楚那。

③复杂而很难注释的代码也许不是什么好代码。如果你发现难以给全部或部分过程加上注释，那么请回头好好观察一下你的代码,你会发现更好的解决办法。

所以，注释不是代码的附属品，它与代码是共存的关系。



注释就是对代码的解释和说明。目的是为了让别人和自己很容易看懂。为了让别人一看就知道这段代码是做什么用的。代码注释有几类
①行尾注释

就是每行代码末尾的注释。这些注释只能用于较短的描述，比如变量。

②内部注释

内部注释是最常用和最重要的注释。使用内部注释可以说明过程的实现方法，使读者能够顺利通过各个不同的转折。如：IF语句、Select Case语句、循环语句、全局变量、重要的变量。内部注释将有益于理解这些代码。

③注释标头。

在模块、类、属性、方法前一行添加注释，以便调用的时候提示用户。注释标头可以包含多个文字项，比如输入参数、返回值、原始作者、最后编辑该过程的程序员、上次修改日期、版权信息，甚至包括程序员喜欢的颜色。

每个注释表头应该有统一的格式，这个我们的net代码规范中已经做了规范了。



当然为了使我们的注释看起来不是很乱，增强注释的可读性。

①易理解-----注释是供人阅读的，而不是让计算机阅读的。应该使注释便于人们理解。难以理解的注释不如不写。

②另外，注释属于文字信息。（用汉语翻译过来，自己的话说出来）---正如应用程序的文字信息，必须清楚地书写一样，代码注释也应该遵循好的书写规则。比如：使用比较完整的语句来描述，不要使用缩写。

③书写---注释通常位于它们要说明的代码的前面。为了从视觉上突出注释与它的代码之间的关系，请将注释缩进，使之与代码处于同一个层次上。



上面已经写了，注释的种类，注释的格式，那么应该对什么进行注释那？

种类	说明
类、过程、方法	描述其的用途（而不是其实现方式）、参数、返回值
输入	输入参数的作用
输出	说明过程返回的值，及其代表的意义
变量	尤其是全局变量，作用范围

这些注释的种类自己在敲代码中认为应该添加的，如有什么不足，请指出。



用文字说明代码的作用，简单地重复代码做些什么，这样的注释几乎不能给代码增加什么信息，（这句感觉自己理解不是很到位）

注释能使代码更加容易理解，更加容易跟踪。出色的注释就像一幅好的设计蓝图，能够引导阅读者通过你的应用程序的曲折之处，能够说明预期的运行结果和可能出现的异常情况。

当然目前自己还是没有达到这种程度，越写感觉自己越不懂。哎…………….