软件开发——软技能（三、注释和文档）

三、注释和文档

    如第一节IDE中所述，绝大部分开源项目的源码跟我们开发的项目源码进行比较，在IDE中除了没有需要优化的地方外，还有一个就是文档注释非常齐全且详尽。LZ估计，在国内公司的软件开发中，对代码注释的强调、要求不少，但在执行或作为检查标准层面上可圈可点。至少在某一线互联网公司提供的某开源软件中，发现某些类中通篇只有一个注释，就是作者的邮箱。并且该开源软件的使用程度也算蛮高，在国内Java开源项目中也算的是一线开源项目。

    很多开发者可能觉得奇怪，为什么LZ会这么重视注释，只要功能实现，程序不出问题不就好了？更有甚者觉得，代码不就是最好的注释？这些都有一点道理，然而LZ认为这些想法都是在对软件工程的思想不是很了解的情况下产生的。软件的生命周期也是符合28法则的，前期的设计开发测试等工作只是软件的整个生命周期的很少一部分，而后期维护和升级则占了整个软件生命周期的很大一部分。所以在对没有注释的软件进行维护和升级是相当痛苦的，尤其是代码中出现词不达意或随意的方法变量名等时，更会提升软件的维护和升级的难度。对于以代码为注释的人，LZ则认为他们没有考虑到在即便在命名能准确表达其含义的情况下，可能出现的重名现象，为了兼容性考虑，而不得不采用类似的命名甚至是不相关的命名。更别说一些采用了缩写的变量或方法了。

    Java提供的文档注释（javadoc）主要有下面几个：

    1.类（接口）注释：描述类（接口）的作用及其用法和使用环境，作者、版本，加入的版本、参考类等；

    2.变量注释：描述变量的作用；

    3.方法注释：描述方法的作用，使用方式，返回值、参数说明，用法示例等。

    个人觉得，在偏重于业务实现的软件开发中，能将上述三种文档注释写好的话，就很不错了，也够用了。但现实并不是如此，在LZ参与过的项目中，除了部分单行注释之外，就只有少量的方法说明，然而这些方法说明也并不符合javadoc的方法注释规范。用javadoc命令生成文档的话，不知道要报多少错误或警告。

     然而最扯淡的现象是这种情况下接口文档的编写。在跨部门或公司的项目中，通常需要提供接口文档和使用示例等。最简单的例子是Web服务端提供给Android端调用的接口文档。对于不会灵活使用javadoc的开发人员，就觉得只好再动手去新建Word文件，画表格，然后再写一个个URL的功能说明和参数说明，再加上一些用法示例等等。甚至美其名曰“文档规范化/标准化”。WTF！！对于这类现象，只想弱弱的吐槽一句，难道人家国外的开源软件提供的以javadoc生成的HTML文档就不”规范化/标准化“了？而且通过javadoc生成的文档查阅起来比Word文件方便的多。更别说在代码中不写注释而去写一份”充当注释功能的Word文档“带来的生产效率低下以及由此造成没有代码注释的恶性循环的问题了。

    LZ在阅读一些开源软件（JDK，Spring等）的源码的过程中，发现常用的javadoc注释标签有如下几种：

    @author               对类的说明 标明开发该类模块的作者

   @version              对类的说明 标明该类模块的版本

   @see                    对类、属性、方法的说明 参考转向，也就是相关主题

   @since                 对类、属性、方法的说明 标明类、属性、方法开始加入的版本

   @deprecated      对类、属性、方法的说明 标明类、属性、方法已经弃用，会引起不推荐使用的警告

   @param               对方法的说明 对方法中某参数的说明

   @return                对方法的说明 对方法返回值的说明

   @throws              对方法的说明 对方法可能抛出的异常进行说明

   @link                    链接到类或方法

    如果要写好源码/文档注释，了解上述文档标签的用法是不可少的。还有一些较少用到的注释标签，以及javadoc后续版本添加的新的注释标签等，都能很好的帮助你在代码注释中展现你的代码思路，同时生成的文档也更容易让使用者理解。

    个人以为，如果去研读开源软件的源码，只是看软件的实现的话，或者说只是学到了开源软件的实现，而忽视了其中的规范，管理流程、方式，一些工具的使用等。那么学了跟没学也没什么差别。经常看到有人拿着一本本JVM原理之类的书在啃，然而发现其代码不是没什么注释、就是词不达意、或者逻辑不清，甚者连基本的Java语法都搞不清楚，对IDE提供的优化提示视而不见，更别说测试用例什么的了。这些代码问题兼而有之的也大有人在。然而LZ想问的是，就算你把JVM研究透了，甚至能写出一个比Oracle（SUN）的JVM性能高很多的另一个JVM，你怎么去让别人用？别人敢用吗？