首页 > 代码库 > 职业规范——注释

职业规范——注释



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

   这个时候这个过程真的很浪费时间,让自己有一种很厌烦的感觉。这是自己的代码,自己编写,自己调试,就有这样的感觉了,如果让你去调试别人的这样的代码,那别人又该有什么样的感觉那??是不是要吐了啊??

   所以说在这个小程序中我是深深的体会到了代码注释的重要性。


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

①写注释太费时间。

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

②有些过程很难注释。

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

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

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

 

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

①行尾注释

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

②内部注释

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

③注释标头。

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

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

 

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

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

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

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

 

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

种类

说明

类、过程、方法

描述其的用途(而不是其实现方式)、参数、返回值

输入

输入参数的作用

输出

说明过程返回的值,及其代表的意义

变量

尤其是全局变量,作用范围

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

 

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

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

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


 

 

职业规范——注释