为什么没有注释的代码浪费我的时间

在编程中,关于注释的使用一直在进行讨论。 一位出色的Swift博主兼书籍作者Erica Sadun过去写了很多有关评论的文章。

最近,安德鲁·沃纳(Andrew Warner)写了一篇文章,说用代码编写注释通常已过时,甚至对您的代码库有害。

评论衰减。 它们不会被编译,并且永远不会在运行时执行。 如果它们过时或不正确,则不会有测试失败,也不会有用户抱怨。 程序员绕着它们工作是因为担心“有人可能需要此注释,或者它将来可能会提供一些价值”,从而使它们在有用之后就走了很远(如果您甚至可以说它们一开始就有用)。

埃里卡(Erica)对这篇文章做出了很好的回应,强调了注释在代码库中的重要性。

注释不仅仅涉及不良的设计和编码。 他们记录了正确编写代码的过程,支持将来的阅读和修改。 好的评论减少了读者每次查看您的资源时所需的精力,使他们可以将更多的精力放在特定的任务上,例如“我如何添加此功能”,而不是“到底发生了什么”。

我完全同意Erica,并且我想强调一种特殊的方式,其中注释可以帮助您的代码读者。

注释不仅针对错误的代码

过去,我主要与比我聪明得多的高级开发人员一起工作,并且在代码中几乎没有注释。 我们在iOS方面经验丰富,通常不会在同一文件上工作。 因此,我们不会经常遇到代码可读性问题。

但是,在我们最近的项目中,我们招募了新员工,一个精明的Java开发人员仍在学习Swift和iOS。 这是我第一次发现我们的代码有时不可读。

在进行配对编程并看到他遍历我们的代码库时,我可以看到他很难辨别Swift或iOS的组成部分以及什么是我们的代码。 看起来他似乎可以很容易地理解一种方法及其作用,但是很难看到所有部分如何组合在一起。

对于UIViewController中更复杂的代码,尤其如此 由于UI代码的性质,动画,生命周期方法,样式和表示之类的不同部分都混合在一起并且相互依赖。

在这里,我注意到我们的格言“注释仅针对错误的代码”散开了。 不管代码有多好,阅读代码都很困难。 弄清楚所有这些不同部分如何组合在一起并非易事。 作为开发人员,使阅读代码更容易是我们的工作。

提供背景

在写文章时,我总是特别注意要写的简介。 其目的是为读者建立上下文和动机,以使其了解文章中的查找内容。

如果您阅读的文章没有前几段,那么您将不得不花前几分钟来试图辨别本文的目的。 它是教程吗? 是新闻文章吗? 是广告吗?

在前几段中,您将注意力集中在尝试分析文章本身而不是实际内容上 。 您也没有必要的上下文来理解本文要说的内容。

一篇文章不仅仅是其段落的总和。 这些段落的流动方式和适合的方式建立了共同的线索,并达到了您想要实现的目的。

代码也一样。 一个类不仅仅是其公共方法的总和。 每个类都有责任(一个要点),并与周围的代码(上下文)相适应。 尽我们所能尝试,使用类总是会影响我们编写它们的方式。 没有方法与呼叫站点完全隔离。 每个类都有适合的上下文。

在读取代码时,如果没有类的上下文,则必须仔细阅读几次,以弄清其中的依赖关系以及它们如何组合在一起。 就像没有介绍的文章一样,这会浪费读者的时间,并且在其他开发人员(或将来的您)尝试更改某些内容时会导致错误。

这就是为什么我绝对建议在每个类(或复杂方法)上使用一个大的注释块,以实质上描述该代码的用途。 每段文字都需要一个简介,为什么一个班级会有什么不同?

永远记住,代码的读取远不止于编写。 针对读者而非作家进行优化。