软件工程说的是用工程学的观点开发软件,工程学就是调配人手去实施大型作业的学问。
因此,软件工程的重点在于人。如果说程序是算法加数据结构,那么软件开发,除了程序这个结果,还要照顾参与开发的人员沟通等问题。就如做房子本来就是水泥和砖头,但是进入到工程领域,就免不了多了很多辅助的工具,比如设计图纸,工程进度之类的,这些东西虽然不构成房子,但是却能用来统筹劳动力。
我们设计软件,也要用到工程学的观点。不能说有些东西不能影响程序的生成,就认为无关要紧。
其中,代码注释就是软件工程的一个我们很熟悉的工具。
有些人说代码最好不要注释,越少越好。这并不正确。人类语言和计算机语言是有差别的,因此我们才需要用人类的语言来注释相关的计算机代码。注释起码有个好处,就算他是完全重复程序代码本身,也能让人迅速的了解程序的意义。你可以觉得注释很“废”,对编写者来说是负担,但是至少从阅读者角度并不会造成什么麻烦。
为了减少对编写者的负担,可以将可有可无的注释给省略。那么这个问题的答案归根结底就是一个注释重要性分类的学问。
以函数注释为例:
1.注释应该说明该函数的作用
2.对参数进行描述,包括提及参数范围,有什么特别值之类的
3.使用代码示例,有些函数比较特别,需要几个函数按照一定的顺序执行,这个如果不加以说明,别人很难知道
总的来说,注释就是尽量让别人可以方便的阅读到相关的信息,并能作出决策。
1.公共函数的注释要比私有函数的注释要重要,因为读者群更广,你总不能要求每个用到你这个公共函数的人,都阅读相关的代码细节吧。如果是私有函数,阅读的人可能就是需要修改你这个函数的人,所以他可能真的需要阅读相关的细节,所以相对而言,注释的重要性要低一些。同理,任何越公共的代码,越多人使用的代码,注释就越重要。
2.注释不需要重复函数实现细节。如果真的要了解细节的,还是让他看代码更好,如果不需要看细节的人,你告诉他细节也是没有意义。但有一个例外,那就是如果这个函数用的是一个很复杂的算法,应该用注释描述一下这个算法。因为算法很多时候都是比较数学化,尤其转化为代码的状态,不是那么直观的看出那段代码到底是做了什么,有注释效果会非常明显。总结,注释应该是将复杂的东西明了化的工具,而不是简单的重复。
3.阅读代码最郁闷的事情,那就是被代码牵着鼻子要圈子,从这个函数跳到那个函数,转了一圈回来你还不知道他干了什么。注释就在这个时候产生作用,尽量避免读者不断的嵌入更大的细节中,让读者从一个比较一致的逻辑层面建立一个宏观的认识。当有函数调用的时候,而这个调用意义不是那么明确的时候,最好注释一下。
反对注释的人,很多都是基于信赖代码自解释的能力。有时候确实可以将注释直接利用标识符来替代。变量的意义,函数的意义,参数的意义,都可以用标识符来做说明。标识符很好很强大(如果能用中文就更好),但是也仅仅限于这些场合而已,而注释却可以用在代码的任何地方。