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

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

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

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

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

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

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

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

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

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

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

打赏支持我翻译更多好文章,谢谢!

打赏译者

打赏支持我翻译更多好文章,谢谢!

任选一种支付方式

5 1 收藏 13 评论

关于作者:小米云豆粥

数据科学进修中,Python小码农。不用QQ,有事站内信联系。 个人主页 · 我的文章 · 30 ·    

相关文章

可能感兴趣的话题



直接登录
最新评论
跳到底部
返回顶部