什么是代码文档化

代码文档化的含义就是要在代码中多写注释，代码文件书写格式规范化，使代码成为良好的文档，一种人人可以读懂的文档，也就是通常所说的良好的可读性。

代码文档化的方法：

1、好的代码样式

a）让“正常”流程贯穿你的代码，异常情况不该扰乱它。

b）避免过多的嵌套

c）还有其它更为基本的，比如代码行不要过长，一行内只有一个语句等等（见前面的坏例子）。

2、选择有意义的名称

a）属性、变量和参数命名

如果是名词性的内容，用名词命名。如user，userName（考虑一下两者的不同），还有elapsedTime等等。如果是逻辑性的内容，要体现出来。

b）函数/方法命名

函数往往表示行为，所以在逻辑上应包含一个动词，如Reset、Start等等。有时还可以隐含参数和返回值的信息，如看到ContainsKey，可以了解它的参数应当是key，而返回值为bool类型的值，表示是否包含该key。

c）类型和命名空间的命名

这些也有一些约定俗成的东西，比如Attribute、Exception和接口命名等等，最重要的是团队内保持一致。

d）文件的命名

一般而言，文件的名字应该能反映出所包含的类型。但在.NET中，有partial类的概念，同一个类的代码可能分布在不同文件中，这时建议先对代码进行合理的分组，其中一个主文件，它的名称与类型名称相同，其它文件以此为基础，并且整个团队保持一致。

3、分解为原子函数

a）一个函数，一种操作：同时为此操作起一个容易理解的名字。

b）减少副作用：副作用总需要额外的说明。

c）简短：虽然是想只包含一种操作，但发现最后的代码竟然有数百行，那说明还不够细化，继续分解，如此递归下去。

4、通过语言层面的机制减少误解

a）如果参数是非负整数，那么考虑用uint来代替int，否则就需要添加注释来说明。

b）如果需要一个不能被改变的值，就使用readonly或const。

c）使用枚举描述一组相关的值。

d）选择合适的修饰符。

5、强调重要的代码

a）在类中按一定的顺序进行声明。比如public的成员放在前面，这往往是读者最需要了解的，可以考虑的一种方式是使用C#中的#region。

b）隐藏不重要的信息，这时自然就强调了重要的信息了。

c）限制嵌套的条件语句的数量，否则就容易掩盖那些重要的条件分支了。

7、考虑上下文信息

在一个地方就只考虑它该考虑的事情。比如异常处理，在团队内可以约定，统一在业务逻辑层进行处理，而不是在任何地方都进行处理。

扩展资料：

代码文档化的优势：

1、产品和文档一致性高

因为产品和文档在同一个流程和工具中开发，文档和代码不一致的现象会减少。代码有更新的时候，文档也可以快速更新。

2、程序员贡献度高

程序员在编码的同时，可以不离开当前环境，直接参与文档。因为操作容易，所以大大提高了程序员的贡献度。例如在Twitter的实践中，一些程序员甚至能贡献第一版的文档草稿。

3、成本低

与工具厂商提供的成套解决方案想比，这种工作模式基本不增加额外成本，深受初创企业喜爱。

鹏仔微信 15129739599 鹏仔QQ344225443 鹏仔前端 pjxi.com 共享博客 sharedbk.com