代码中的注释情况：优于问题跟踪器、风投等。

当我第一次开始编程时，特别是当我被要求提供代码样本时，我的评论缺乏目的性，经常会用英语重复代码清楚地指示的内容。我知道评论是件好事，但作为一个初学者，我没有进一步的洞察力。

随着时间的推移，在像“干净代码”这样的书的帮助下，我变得对评论不屑一顾。好的代码应该是自文档化的。每当我需要写注释来解释某事时，我就会意识到我可以很容易地重命名一些关键变量或函数。在标题中加上几个字，我对变量和函数就变得更习惯了。最好把时间花在良好的代码结构和命名上。

不过，我总是离开TODOS，因为TODOS不能很容易地用变量名来表示。但即使是这些待办事项也让我感到担忧，因为它们存在于我的问题跟踪器中，或者也许应该存在。

当我看到成熟的开源项目和成熟的工程师时，我开始重视记录良好的拉请求。可靠的拉入请求包括指向所有必要背景的链接、失败或忽略的机会、如何使用、指向需要解决方法的外部错误的链接以及性能评估结果。

除了Pull Request描述之外，当我真的想给APULL Request加油时，我会使用Pull Request UI来添加注释，让读者注意差异行中的关键更改。

但是，当我在代码中发现错误时--我知道有很好的Pull请求文档，即使是6个月前的Pull请求--Github和GitLab公布的Pull请求和Pull请求注释搜索都一再失败。

我知道在请求线程中有指向记录的怪事或错误报告的链接。但实际上，对于历史拉取请求，拉取请求注释是无用的。

这是我开始推动在代码中添加更多内容的最大原因。这比所有其他工具(问题跟踪器、代码需求管理系统等)都要好。如果代码中的注释没有被删除，那么它们很有可能仍然存在，并且很容易被搜索到。

不要让我开始在外部介质(如Slake)中查看拉取请求文档。在即时信使上获得或给出即时反馈是非常有意义的，但祝你在3个月后找到讨论的机会很幸运。

每次我必须调用Pull请求中的一行代码时，都会立即使用注释修改该代码。

如果Github/GitLab公开了一个类似Google Docs的界面，可以逐行浏览代码，并链接到所有的PullRequest评论线程，也许我就不会这么做了。

在代码中添加注释的最大原因(通常链接到记录的怪事或错误报告)是因为不可能在我使用过的每个源代码管理UI中搜索历史上的拉请求线程。Https://t.co/JlHWfbUH5z。

-菲尔·伊顿(@Phil_Eaton)2020年9月8日