写代码做文档

       我记着以前的公司是一个很正规的公司，架构的人写好代码，也会写一份帮助文档出来，这样我们做实施的就可以不用担心有些问题是否需要自己去写，还是直接去调用util的方法，那会自己还是一个应届毕业生，能够去参与写util方法并且去想文档中加一些方法注释感到很兴奋，好像自己在做什么开源软件似的，那会太单纯了，不过话说回来，这种写代码做文档的工作确实是很有用的！假设一群开发人员在一起制作一个大型的项目，如果每个人的逻辑块对外接口都没有统一到文档中，那对工作进度是有相当大的影响的，如果每个人需要的时候都去问相关的开发人员，或者干脆自己去看源代码是怎么完成的，这要耽搁很多时间！而且随着项目的扩大，对外接口的数量上的增多，加之期间可能会有不了解项目的新人加入，那就更可怕了，所以一个正规公司的项目，一个好的接口文档是相当必要的！

 

 

       我现在的公司类似一个开发团队，服务端这边是没有什么接口文档科研的，而我记着我刚进来的时候，如果想要去了解一个逻辑块的对外接口和返回值我就去问，时间久了自然会惹人烦，没办法我就要去到源码中找到相应的位置，方法无外乎三种，实际操作，去跟消息，例如我想知道物品时怎么生成的，那么我就要去日志里看客户端的消息发送到服务端以后服务端都调用了那些方法，而这些方法重是否就包含了我所需要的接口方法，还有就是，直接根据注释去逻辑块中去找，如果够幸运，不许要太长的时间我就能找到，但是如果开发人员注释写的不好，或者是写的很奇怪，那就麻烦了，我要把代码从头看一遍，然后根据需要确定自己选择哪个，还有一种就全靠我的Editplus编辑器的目录搜素功能了，我把可能调用的接口名直接打上去然后群居搜索，看是否是我想要的外部接口！这样看着是不是很费劲？确实如此，那会作为一个新人来讲，着实把我难住了，有的时候许多属性的变换都是在同一个消息中去传递的，也就是说，你追着消息走可能拿到的根本不是你想要的方法！不过不得不说，这逼得我那会把代码基本看了个遍，后来有了时间又把不知道的东西再琢磨了一遍又一遍，那阵子成长是相当的快了！（真是人随着环境变啊）。

 

 

       这就看出来文档的重要性了，想要快速的开发并且能保证后进人员能够快速上手开发或者维护，文档真的是必不可少的，其实写文档快的很，一个人做好模板，放到版本管理器上，例如svn，然后谁写了新的外部接口就在上面写好注释和说明，对于开发的时间和人力消耗而言，维护一个接口文档的时间完全是可以忽略不计的，但是带来的方便确实有目共睹的，所以何乐而不为呢！！！！