不给代码写文档，让代码文档化

（给 伯乐在线 加星标，看经典文章 ）

编译：伯乐在线/小米云豆粥

这是程序员讨论了很久的一个话题：要不要给代码写文档？值得给代码写文档吗？

我曾经觉得这个话题实在是让人难以应付。也认为除去一些特殊的情况（比如编写公用 API），代码文档并不是那么必要。直到有一天，我在一份代码检查报告中发现，缺少文档被作为一项缺点指出来。真是这样的吗？

我曾经也给我的代码写文档——至少我尝试了。我曾深信你必须给代码写文档。以后对我自己，或者对其他需要看我的代码的程序员来说，文档都会是一个好的提示。直到我发现大部分代码文档无法反应最近更新，我就开始思考：“如果无法保证文档反应最近更新， 那写文档的意义到底在哪里呢？”

这个想法持续到前几年，直到我读了《代码整洁之道》这本书。我清楚认识到，如果你将文档写入代码，你就没有必要再为代码写文档了。

我的意思是，使用有意义的变量名和函数名。如果变量名字已经表明了它们所代表的意思，函数名也清楚说明了它们所实现的功能，那么你完全不需要去读代码或者读文档来弄明白代码的作用。

编写方法的时候，即使最后你的方法只有三四行代码，也要尽量让代码简洁。一个方法应该制作一件事情，而且方法名要表明它的功能。

对于一个类里面的每一个成员名，都应该达到只读名字就知道它们所包含的信息。这个规则对变量和输入参数也同样适用。

遵从这些将文档写入代码的规则，你就能写出可读性很高的代码。

是的，我知道，总有一些时候你需要写代码完成一个复杂的算法，或者你从网络上找到了一些复杂的不容易看懂的代码，你无法从中提取简洁有用的方法。是的，总会有例外。

你是怎么想的呢？你是给代码写文档，还是将文档写入代码呢？欢迎在评论中留言。