编写自文档化代码

本系列文章由 @yhl_leo 出品，转载请注明出处。
文章链接： http://blog.csdn.net/yhl_leo/article/details/50545047

---

严肃是写作必备的两个因素之一。另一个，很不幸，是天分。 —— 欧内斯特$\cdot$海明威

个人觉得可以把一个人编写程序所处的阶段可以分为四个：

• 识字：接触和掌握了一些基本的编程知识（变量，类型，函数，……）和语法（运算，循环，判断，……）；
• 造句：可以根据基本的知识和语法模仿甚至自主实现一些小的算法等；
• 自由表达：熟悉掌握编程语言后，只要不太复杂的算法，似乎只要知道算法原理，就能实现；
• 妙笔生花：此时，你可能意识到代码实现不再是你所追求的目标，创建优秀的代码对你而言更具吸引力和挑战性。

创建优秀的代码意味着创建良好的文档化的代码。我们编写代码的原因是要表达一套清晰的指令——不仅仅是对电脑，也是对那些以后需要维护或拓展这些指令的可怜傻瓜们。所以，千万不要去膜拜把原本简单易懂的代码写得反人类的所谓大神！现实世界中的代码从来没有在编写完成后就被遗忘掉。在软件产品的生命周期内，这些代码将不断地被修改，拓展和维护。想要做到这一点，我们需要说明指导，即一个文档化的用户指南。

对于代码的文档化，人们通常的做法是编写大量的关于代码的文档或者在代码中添加大量的注释，这两种方式都是明智的。

实际上，这两种方法都是无稽之谈。大多数程序员对文字编辑器唯恐避之不及，对于编写太多注释也是相当头疼。编写代码是意见艰苦的工作，而将代码文档化更是艰苦异常。

对于支持文档的系统，常常面临以下挑战：

• 我们不需要做额外的工作。编写文档非常耗费时间，阅读文档也是这样。程序员们更愿意将时间花在编写程序上。
• 所有的独立文档都必须随着代码的更新而不断更新。在大型项目中，这将是一项可怕的工作。而不更新任何文档将会导致危险的错误和产生错误的信息。
• 大量的文档是很难管理的。在大量的文档中查找正确的文档，或者寻找在一个文档中可能多次出现的信息是不易的。就像代码一样&#x