事先声明一下，这篇文章是为完全没有任何文档编写经验，并且正在使用Visual Studio的同学们准备的，不一定适用于老鸟以及其他IDE爱好者 ：-）
Ok， alpha版本的一个严重的问题便是，我们没有任何的文档积累；所以在Beta版本的开发中，PM准备彻底消灭这种无文档的编码风格。
既然要让大家写文档，那么总该有个文档规范吧！理论性的东西我就不多讲了，这里我就讲一个“南七规范”——简单实用，不用费脑子。
南七规范 v1.0
不知道提到“文档”，同学们首先会想到什么东西——不过我估计大概是这样的风格——工程里面有一个doc目录，然后里面有各种不同开发人员维护的xxx.txt文件（或者微软式xxx.doc）；诚然，有很多工程的文档组织形式就是这样的，但是这样做也有缺点，就是文档可能一旦被写出来就落后于代码了——离代码太远。还有一点就是分开维护的文档可能覆盖面太窄——代码中会出现很多没有在文档中提到的方法。
所以在这里向大家介绍另外一种维护文档的方法——注释法（名字是我自己发明的，不要打我）。意思是说，程序员只需要在每个函数（或者类）开始之前加上一段特殊格式的注释，然后就可以用专门的工具扫描整个代码树然后转换成按照架构组织好的（带有多种目录，甚至还可以搜索）html或pdf文档。
这种方法的优点在于，当一个方法被重构的时候，程序员可以轻而易举地修改文档，做到二者同步，而且如果保持每天都把文档给Build出来的话，可读性又很高。
我们的南七规范规定——必须给每个函数加上文档，所以在每个函数前面，都必须写一份注释。
上个例子吧。
///<summary> void StartGame(int songID,int level) |
注意代码上面的那段注释，特殊之处在于普通注释都是两道杠，这个文档注释是三道杠，尽显尊贵。看到这里大家可能会说，麻烦！我告诉你，一点都不麻烦，只要你是在使用Visual Studio，那么你把光标停在函数头的前面，按一个三道杠——啪，自动补出来了，剩下的工作就是往里面填入内容而已！
聪明的同学们可能已经观察出来了——三道杠里面套的不就是一些XML形式的结构么？（再不明白的话，就像HTML一样）于是就挨个填内容吧——下面来几个裸按三道杠补出来的样板做示范——
| ///<summary> /// ///</summary> ///<param name="position"></param> ///<param name="tag"></param> private void AddButton(Rectangle position,int tag) { TransparentButton tbutton = new TransparentButton(position,tag, this); buttonList.Add(tbutton); } |
这便是在任意一个函数前面按下三道杠之后自动补全的结果。可以看到整个XML结构分为两个部分，一个叫summary，另一个是一堆param。
summary部分是对这个函数的作用，行为的描述，我的建议是，这里的描述要像说明书一样——你在写注释的时候就要假设有个十万个为什么正在问你，这个函数应该怎么用，输入什么，吐出来什么，副作用是什么——但是不要牵扯到太多内部实现的细节——什么把XXX对象加入到_YYY队列中——这明显不是说明书应该做的事情，要想弄清楚这些事情，最好的方式是读代码（相信我，这种情况下看代码比看注释清楚又高效）
