代码少写注释_注释很少改善您的代码

代码少写注释

关于代码注释的争论正在进行中。 在过去的30年中，我每年至少参与一次有关该主题的讨论-经常是偶然而又不情愿的。 老实说，随着时间的推移，我的观点发生了变化。 我曾经注释过每种方法，曾经注释过“怪异”的任何代码行，并且曾经注释过任何过于复杂的代码块。 今天，我很少评论，如果有的话。 随着时间的流逝，我逐渐意识到大多数评论都是不必要的。

我看到的大多数评论都属于以下几类之一：

• 文档-代码的结构化文档，理想用于自动创建参考手册
• 说明-描述代码块的功能
• 沮丧-表达对代码或情况的不满
• 欢乐-开个玩笑

其中，文档和说明可能会改进代码，但通常不会。 挫败和欢笑不能改善代码。

文档是结构化的注释，通常是在函数或方法的声明中描述了代码的作用以及预期的输入/输出。 这些注释并非旨在改进代码本身。 它们旨在记录代码。 理想情况下，这些注释会被某些第三方工具清除，并用于生成参考手册。 在编写良好的源代码中，大多数（如果不是全部）信息都应易于从声明本身中收集。

命名正确的方法将指示名称中提供的行为。 命名正确，格式正确的参数和返回类型将进一步指示该方法的功能。 此时，该注释是多余的，保存了生成的外部文档。

解释是描述代码功能的注释，或者是解释代码为何如此运行的某些原因。 文档和说明之间的主要区别在于结构和位置。 说明注释可以出现在代码中的任何位置。 他们可能会解释整个方法或方法的一行。 它们通常是不必要的，而且很有趣的是，它们为我们提供了有关如何更清楚地编写代码的线索。

这是带有注释的函数调用：

// Determine if item can be purchased with credit remaining
Boolean allowed = checkItem(Int id, Float amount)

该注释告诉我们如何更清楚地编写代码：

Boolean isCreditPurchasable = canBuyItemWithCreditRemaining(Item item, Float creditRemaining)

如果在代码块上找到解释性注释，则很可能表明该代码块可以被提取为具有描述性名称的函数。 如果该块执行了许多操作，则也许可以将这些组件提取到每个函数中，每个函数代表一个离散的步骤。

挫折与欢宴是为了阅读低实用。 当时他们对作者可能感觉很好，并可能给读者带来笑声或同情心，但是他们并没有改善代码本身。

现在，有人将提出必须注释某些代码的论点。 在代码本身之外的情况下，其他任何情况都不会显而易见。 当然。 也许。 这种情况很少发生，这就是为什么我指出文档和解释可能会改进代码。

如果您想不出一种在代码本身中明确表达它的方法，请对其进行注释。

先前发布在https://docondev.com/blog/2020/5/1/comments-rarely-improve-code

翻译自: https://hackernoon.com/comments-rarely-improve-your-code-u36n3yca

代码少写注释