面向对象编程的文档制作与管理

面向对象编程的文档制作与管理

  编码是一项工作量极大的工作，而阅读学习别人的代码同样不是一件容易的事情。那么为了方便代码的后续维护工作，必须在编码阶段就将这件事情考虑清楚。今天专门介绍这个问题。
 

  首先，编写代码的人需要注意代码的风格以便于维护人员可以省去阅读上的麻烦。比如：
1）变量/函数的命名需要含义清晰，不可以出现模糊或者无法理解的现象。
2）代码的缩进要复合逻辑的关系，这样可以在只关心代码的某个条件下的某个行为的时候，一下子抓住该部分内容而不需要通篇阅读所有的代码！
3）自定义的类型要与系统定义以及第三方库的名字却别开来，这样可以更方便定位问题在哪个范围（谁的代码由问题）；
4）注释一定要完整清晰，而且尽量注释，就是说在可以注释的地方尽量注释代码，类型，变量，等的含义，目的，参数等。方便使用该代码的人员准确使用.

  以上是编码的一些基本原则,不是很完整.但是今天的重点是代码文档的制作!这个问题在计算机编程的初始阶段就已经有很多人考虑到并一致致力于完善代码的维护工作.Doxygen是一款使用简便,功能强大的工具,可以方便的辅助编码人员由源码生成自己需要的文档.
 
 天下没有免费的午餐!同样要使用Doxygen从源码生成方便阅读的文档是需要付出一点代价的.那就是我们需要在编码的时候注意自己的注释风格,按照指定的注释方式(该工具支持Java风格的注释风格,C++风格的注释....)对自己的代码进行注释就可以在工具生成本文的时候将我们的注释信息融入到文档中，从而生成一份更加符合编码人员的"说明书".

Doxygen介绍

  Doxygen是一个强大文档生成工具，使用简单尤其是windows下的拥有UI界面的版本更加方便。同时它是一个开源的工具使用中不会收取任何费用以及产生任何知识产权方面的问题。下面我们就来学习一下这个工具的使用。在此我使用我最为熟悉的c++语言作为讲解的实例。
  Doxygen的工作原理比较简单，他通过扫面用户指定的工程文件，提取程序员编写source code时候按照要求编写的comment生成具有各种方便阅读格式的文档。这些包括class的派生关系（包含树形关系以及图形化的结构）；class数据成员以及函数成员的注释等等。必要的时候可以选择取出一些内部接口生成一份简洁而又方便的外部接口式样书等操作。

  这个软件工具可以从开源网站

获取win版本的binary或者类Unix版本的binary或者source code。
在该软件的主站包含了每个版本的发布信息以及使用帮助。由于安装方便异常简单所以此处不予介绍。
  下面介绍一些编码的时候得工作以及如何配置Doxygen才能生成一份我们需要的文档。

  编码注释的方式。Doxygen本身对注释的风格支持的比较强大：Java风格，c++风格；等等，详细地内容可以参阅

文件:	doxygen_manual-1.5.7.1.pdf
大小:	1035KB
下载:	下载

  以上是目前最新版本的使用帮助说明，可以方便参阅。

实例：

以下是本人開發的運行于XP上多線程以及event系統的文檔

文件:	ESThreadSystem_By_Stephen_Du.rar
大小:	683KB
下载:	下载