项目那点儿事---山寨篇（注释不是程序员的负担）

       一直在关注羽之的项目那点事系列，写的非常好，推荐大家关注下。在标准化的意义 那章中和博主讨论了一下，发现回帖有些长，所以就独立的回复一章，才有了这个山寨篇。本文着重讨论标准化的注释，如何使程序员喜欢注释、习惯注释。此文全当抛砖引玉，希望园友不吝赐教，引来更多金玉良言.

首先描述下我们的团队结构和开发流程。

结构：
我们有自己的基础模块和开发框架，这些有1-2个程序员共同维护。其作用主要是作为代码生成器的基础。

代码生成器，由1个人开发（本人^^），和通常大家用的差不多，功能类似于动软，不过是基于团队的框架，另外可以通过配置生成web页。

业务程序，在框架和代码生成器基础上开发业务逻辑，这个要根据项目的规模确定开发人员数量。


开发流程:
1.开发前我们架构人员（有时候和实现是同一个人）都会写一个详细的项目分析文档，一方面是给客户看，另一方面是团队看。在客户确认后才开始编码。
2.生成代码
3.业务开发
4.组装
5.上线


这些大多公司都差不多。就不详细表述了。



我大多在项目中推行的是自动化开发
既采用重复代码自动生成（根据我们的框架写的代码生成器），生成器会自动生成注释。

至于作者、日期
这个我们会在vs中新建模板页来解决，创建新的项也会自动的生成这些信息。
修改记录不属于强制注释

其他的比如类功能是必须的（输出一般也写在功能注释中），因为程序员在实现以前就要知道功能是做什么的。
参数列表也是必须项，这个也是写程序时候边写边改的。不过通过vs的自动注释功能只需要填写参数的功能即可。

最后要做的就是数据字典，这个我们还是依赖代码生成器，规则的命名会自动生成注释，非标准的命名会留出空余，让程序员自己填写。

当然其他的一些注释则是根据项目的大小，时间进度的因素弹性控制的。

这里我们应用了很多技巧，例如代码生成，vs页面模板等，有了这些东东我们的程序员在开发的时候做注释花不了多少时间，大多数都是自动生成的，一般一个模块下来也就个把分钟。
而程序员的模块在写完以后很少有不需要修改的，有了这些注释不仅程序员不会感到有负担，再日后修改的时候也会觉得轻松很多，所以我团队里的开发人员已经自觉的形成维护注释的习惯了。

业务层部分
此前我们已将实现了作者、日期等的自动化。
在编写业务层的时候大部分模块都是重复的，比如权限，信息发布，公文流转，进销存等，这些都可以形成基础模块，这些基础模块由固定的人来维护，由于可能会定期修改，所以这些维护的工作人员即使你不规定他们也会自己添加注释（要选对人，有责任感的）。

另外，开发需要一套命名规范，可以用微软的指导性文件，也可以公司统一编写一份，这样大家在看到命名的时候只需要配合很少的注释即可快速上手。

至于特殊的业务比如统计报表，个性模块这些就没办法了。但是由于这些模块只会被很少的用户用到，所以相对来说复用性不是很好，只需要简单的注释即可。
要求程序员标注方法功能，参数列表，模块功能即可，这些工作基本不会加重程序员的负担，而稍微上手的程序也会自觉填写的。

其实自动化注释工具只是一个辅助，只能进行共性代码和功能的辅助。最重要的还是在让程序员参与这些共性代码的开发时养成注释的习惯，让程序员自动、自觉的去写注释，这才是自动化注释的终极目标（失少是我的）。

关于注释的长度
我们编写注释的习惯是简短明了，一个接口、一个方法的注释在vs中输入///以后会自动生成一个模板，程序员只需要填写就可以了。功能只需要一句话，比如 //阿拉伯数字到汉字的转换。
参数也是，之后再调用的时候注释会和.net提供的其他方法一样显示这些注释内容。

模块方面也是类似，只是多了一些信息，比如作者，时间等等。

所以，并不会有冗长的内容，也不会让阅读者觉得累赘。