软件开发浅谈

注释
注释这个问题老生常谈，但是往往在开发中贪图一时爽快，老子天下第一，要什么注释. 确实注释这个东西是比较反人性，也不容易看到短期的利益，
但是如果我们把时间拉长，把工程做大，你大概慢慢能体会注释的重要性：

• 1.1 把时间拉长
  

       程序员从不怀疑自己的记忆力和理解能力，总能在茫茫代码中找到自己想要的东西，但这种说法前提是你目前正在开发或者维护该模块代码，
       时间一长，模块稳定后，你基本很少会花时间来review以前写的code，但是稳定也只是相对的，不同的应用场景，不同的调用时序，总会可能
       在一个你认为很稳定的模块中发现bug，老子代码已经稳定很多年了，不可能有bug，说归说，bug还是要解的，隔了这么些年，你前女友的样子
       都该忘了吧，更别说自己曾经写的那一坨，所以开发的时候多写点注释，也是为了未来能过的幸福点呢，你说是不~

• 1.2 把工程做大
  

        单片机的proj可能都不会太大，但稍微复杂点的项目总还是要和你的队友co-work的吧，一般是你们约定好API后就各自回家开发去了，但有时候
        也可能你们的模块开发有时间的先后性，这个时候往往模块A先开发完成，然后代码release给B，让B按照你定义好的API来接棒开发，老子API
        包的很规范，非常好用，那你看这又是你的一家之言了，接口调用之间是否有依赖性，是否线程安全，是否同步接口？这些你都没有说明，你
        就等着B安安静静地开发bug吧，到头来你还是要帮助别人一起解bug. 所以写点注释吧
写了以上两点，很片面，但希望能够理解注释的重要性. 诚实的说，每个API都写注释是费神又无意义的事，比如有些文件内部使用的一些工具写函数
你可能就没必要写出来， 主要是那些主功能函数接口和一些对外接口，这些确实需要注释的。

下面我再讲讲注释为什么要规范，最好是统一，这不仅仅是为了给阅读者以视觉的享受，更是有他实用的一方面。有个概念叫自动化文档，对，就是
写完code，API的使用文档就跟着出来了，而不需要你额外再撰写文档啦（尤其和客户合作开发的时候，文档是必需的吧），如果注释足够规范，我
门就可以使用脚本（perl, shell）自动扫面代码，并把注释生成文档（html），下面是现成的自动化代码文档工具，功能强大.

用doxygen+graphviz自动化生成代码文档（附详细教程）

• 未完待续