如何将编写好的文档化代码转换成长尾词？

本文共计4484个文字，预计阅读时间需要18分钟。

文以载道也。对于程序员来说，我们的工作也是写作——几乎每天都要写代码；而且还要‘载道’，不仅要满足客户的需求，还要让代码具有‘道’——即充分体现程序的本质。

文所以载道也。 —— 宋·周敦颐《通书·文辞》

对于我们程序员来说，我们的工作也是写作——几乎每天都要写代码；而且还要载“道”，不仅仅要满足客户的需求，还要让代码具有高度的可读性，这样其他的程序员可以更容易地对代码进行修改和扩展。

按这样的要求，我们需要为代码编写足够的文档，也就是将代码“文档化”。常见的做法有两种，外部文档和注释。

外部文档

外部文档指的是在代码文件之外编写的附加文档，比如在Word文档中采用大量的篇幅（如UML图、表格）来设计或记录相关的包、类型、类型成员、成员参数之类的信息。这看起来很规范，但如果你用过这种方式，一定会讨厌它。这种方式的主要问题在于：

1）增加很多额外的工作：编写代码本身的压力已经很大，在压力之下，我们往往选择做那些最必需的事情，就是实现功能，如果时间紧急，编写文档就可能是草草了事了。

2）文档需要与代码保持同步：即使你在开始认真编写了文档，后来代码有了修改和扩展（这是不可避免的，即使采用所谓的冻结需求），那么文档就需要更新，否则就会提供误导信息。

3）大量的文档难以管理：如果代码量较大，那么本身就需要大量的文档；同时文档也需要进行版本管理，那么就产生了不同版本的文档；另外这些文档基本上是一些简单的文本。如此一来，要在这些文档中找到所需的信息，难上加难。

文档具有这些问题，一个重要的原因是，它们离代码太“远”了。我们可以将它们搬到代码文件里面，这就是第二种做法：注释。