代码与批注

       通常我们写代码时，或多或少都会加上一些批注，也有一些程序猿不屑与写注释，认为自己写的代码叼炸天。通常不规范的注释对后期的维护，后期文档处理等都事倍功半。

       根据调查，软件企业一般要求50%以上，有些日企甚至被要求注释覆盖率占90%以上，虽然不知道各个公司对覆盖率的描述如何，但是足以看出注释的重要性。认识一个学长在维护另一个老学长做的软件，文档以及代码注释写的比较乱，现在大约花费了半年的时间依然没有把软件重新搞明白。

      首先说注释的作用一和二，便于理解以及便于后期维护等等，不必多说。

      其次，另外一个特别重要的作用是对于软件说明文档的编写。据我所知，很大一部分同学不会注意到这方面的问题。因为没有人提醒过。而印度等国家对代码的注释是非常重视的，他们一般都可以直接生成文档，下面对直接生成文档做简要的说明。

不知道大家有没有听过Doxygen这款软件，良好的注释风格可以直接利用Doxygen生成软件说明文档，并且其中包含了各种说明，甚至于类图等等。

下面是一些注释风格，对于注释，有

JavaDoc类型：

/**

* ... 批注 ...

*/

Qt类型：

/*!

* ... 批注 ...

*/     

单行型式的批注：

/// ... 批注 ...   或    //! ... 批注 ...

举例来说（JavaDoc）

/**

     * 自订类别的member_funtion说明 ...

     *

     * @param a 参数a的说明

     * @param b 参数b的说明

     *

     * @return 传回a+b。

     */

int MyClass::member_function( int a, int b )

    {

        return a+b ;

    }

这其中@param a以及@return等都是Doxygen所有的命令性的语句，它可以识别。

        

      另外提及一些命名规范，比如匈牙利命名 变量名=属性+类型+对象描述 等，关于命名方式论坛到处有。

       当按照Doxygen要求的命名规范之后，可以用该软件生成软件分析说明文档，不管是.chm格式的还是.htm格式以及pdf等，都可以自动生成，生成的文档中包含类的结构，类图，以及各种参数的说明等。

       总之，写这篇文档主要是两个目的，一是提醒一下注释的规范问题；另外，对于软件的生成文档问题。