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

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

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

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

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

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

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

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

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

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

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

不给代码写文档，让代码文档化相关推荐

Python+Streamlit aggrid+MongoDB GridFS构建低代码文档管理应用（文档查询下载实用篇）
1. Sreamlit aggrid简介 Sreamlit aggrid是Streamlit的Ag-Grid组件的实现,在Python Streamlit框架下,更加灵活的使用表格,包括分组.排序.编 ...
NDoc –NET 代码文档生成器快速度上手
感谢:破宝 http://blog.joycode.com/percyboy/ <?xml:namespace prefix = o ns = "urn:schemas-microso ...
vue 插入word模板项目_10 分钟为你的 vue 项目编写代码文档
代码文档是软件开发使用和维护的必备资料,有了文档,开发和维护以及协作的效率将变得大大提升.tips:如果对 JSDoc 已经熟悉,可以直接跳到实战演练环节. 什么是文档?软件文档或者源代码文档是指与软 ...
代码文档生成工具-Doxygen生成CHM和RTF图文教程
Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,可以从一套归档源文件开始,生成chm格式的文档.本文主要讲解如何在winddows下安装doxygen. 1.下载doxyge ...
火车车次查询api代码文档及返回示例分享
火车车次查询api代码文档及返回示例分享,支持出发站名称.到达站名称.车次类型等查询,将其集中到APP中,使用更加方便. 接口名称:火车车次查询api 接口平台:api接口接口地址:http://a ...
python如何读取公共盘的文档_如何使用 Sphinx 给 Python 代码写文档 | Linux 中国
最好将文档作为开发过程的一部分.Sphinx 加上 Tox,让文档可以轻松书写,并且外观漂亮.-- Moshe Zadka Python 代码可以在源码中包含文档.这种方式默认依靠 docstring ...
python代码_如何使用 Sphinx 给 Python 代码写文档
最好将文档作为开发过程的一部分.Sphinx 加上 Tox,让文档可以轻松书写,并且外观漂亮.-- Moshe Zadka(作者) Python 代码可以在源码中包含文档.这种方式默认依靠 docst ...
代码文档生成工具Doxygen教程及实例
程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具[Doxygen]生成. 什么是Doxygen? Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件.通 ...
开源免费,又一款代码文档生成工具
原文链接:https://gitee.com/sharetech_lee/DevWeekly DevWeekly收集整理每周优质开发者内容,包括开源项目.资源工具.技术文章等方面. 每周五定期发布,同 ...

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

不给代码写文档，让代码文档化相关推荐

最新文章

热门文章