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

（点击上方蓝字，快速关注我们）

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

如有好文章投稿，请点击 → 这里了解详情

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

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

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

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

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

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

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

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

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

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

据说程序员讨厌两件事：写文档，别人不写文档；—— 网络段子

推荐阅读

《程序员最头疼的事：命名》

看完本文有收获？请转发分享给更多人

关注「程序员的那些事」，提升编程技能