Question

我已经看到了的其他问题，但我仍然不满意这个主题的涵盖方式。

我想在代码检查时提取一份废弃的商品清单以查看评论。

我相信人们会说会相互抵消的事情。但是，嘿，也许我们可以为每个阵营建立一个清单。对于那些根本没有发表评论的人来说，这将非常简短：）

Answer 1

我有一条关于评论的简单规则：你的代码应讲述你在做什么的故事;你的评论应该讲述你为什么这么做的故事。

这样，我确保无论谁继承我的代码都能够理解代码背后的意图。

Answer 2

我使用元注释评论公共或受保护的函数，如果我记得的话，通常会点击私有函数。
我评论为什么存在任何足够复杂的代码块（判断调用）。 为什么是重要的部分。
我评论如果我编写的代码我认为不是最优的，但我留下来因为我无法找到更聪明的方法，或者我知道我将在稍后重构。
我评论提醒自己或其他人缺少功能或代码中没有的要求代码（TODO等）。
我评论解释与一个类或一大块代码相关的复杂业务规则。我知道会写几段以确保下一个人/ gal知道为什么我写了一百行。

Answer 3

如果评论已过期（与代码不符），请将其删除或更新。永远不要留下不准确的评论。

Answer 4

编写尽可能不言自明的可读代码。每当您必须编写太复杂而无法一目了然的代码时，请添加注释。还要添加注释来描述您编写的代码背后的业务目的，以便将来更容易维护/重构它。

Answer 5

文档就像性;什么时候好的，非常，非常好，什么时候它很糟糕，它总比没有好

Answer 6

在实现RFC或其他协议规范时，使用与其对应的规范部分对状态机/事件处理程序/等进行注释。请确保列出规范的版本或日期，以防以后修改。

Answer 7

您撰写的评论可以揭示代码的质量。无数次我删除了我的代码中的注释，用更好，更清晰的代码替换它们。为此我遵循了几条反评论规则：

如果您的评论仅仅解释了一行代码，您应该让这行代码说明一下，或者将其拆分为更简单的组件。
如果您的评论解释了函数中的代码块，您可能应该解释一个新函数。

对于两种不同的情境，这些规则实际上是相同的。

我遵循的其他更正常的规则是：

使用动态类型语言时，记录重要函数对其参数的期望，以及调用者对返回值的期望。重要的功能是那些将拥有非本地呼叫者的功能。
当您的逻辑由另一个组件的行为决定时，最好记录您对该组件的理解和期望。

Answer 8

我经常在写一个方法之前评论一个方法。我将在函数中为每个步骤写一行或两行注释，然后在注释之间编写代码。当我完成后，代码已经被评论过了。

关于这一点的重要部分是它在之前评论了我编写代码，因此对评论中的先前知识没有不合理的假设;我自己在编写代码时对代码一无所知。这意味着它们应该很容易理解。

Answer 9

我写了一篇关于糟糕评论的完整文章。享受：）

How bad comments are born in your code

Answer 10

没有严格的规则 - 严格的规则导致教条，当人们不够聪明，不能自己思考时，人们通常会遵循教条。

指南我遵循：

1 /评论告诉我们正在做什么，代码说明它是如何完成的 - 不要重复你的努力。

2 /评论应该引用代码块，而不是每一行。这包括解释整个文件，整个函数或只是一个复杂的代码片段的注释。

3如果我认为我会在一年内回来并且不理解代码/评论组合，那么我的评论还不够好。

Answer 11

评论的一个很好的规则：如果你正在阅读代码试图解决某些问题，并且某个地方的评论会给你答案，在你知道答案时就把它放在那里。 / p>
只花时间调查一次。

最终，当你写你需要留下指导的地方时，你会知道，以及那些非常明显的地方。在那之前，你会花时间浏览你的代码，试图找出你做某事的原因：）

Answer 12

我记录了每个类，每个函数，类中的每个变量。简单的DocBlocks是前进的方向。

我通常会为自动化API文档编写更多这些docblock而不是其他任何内容......

例如，我的一个PHP类的第一部分

/**
 * Class to clean variables
 *
 * @package     Majyk
 * @author      Martin Meredith <martin@sourceguru.net>
 * @licence     GPL (v2 or later)
 * @copyright   Copyright (c) 2008 Martin Meredith <martin@sourceguru.net>
 * @version     0.1
 */
class Majyk_Filter
{
    /**
     * Class Constants for Cleaning Types
     */
    const Integer            = 1;
    const PositiveInteger    = 2;
    const String             = 3;
    const NoHTML             = 4;
    const DBEscapeString     = 5;
    const NotNegativeInteger = 6;

    /**
     * Do the cleaning
     *
     * @param   integer Type of Cleaning (as defined by constants)
     * @param   mixed   Value to be cleaned
     *
     * @return  mixed   Cleaned Variable
     *
     */

但是，我还有时会记录重要的代码（来自我的init.php

// Register the Auto-Loader
spl_autoload_register("majyk_autoload");

// Add an Exception Handler.
set_exception_handler(array('Majyk_ExceptionHandler', 'handle_exception'));

// Turn Errors into Exceptions
set_error_handler(array('Majyk_ExceptionHandler', 'error_to_exception'), E_ALL);

// Add the generic Auto-Loader to the auto-loader stack
spl_autoload_register("spl_autoload");

而且，如果不能自我解释为什么某些事情会以某种方式发生，我会发表评论

Answer 13

我在代码的开头创建了一个注释块，列出了程序的用途，创建日期，任何许可/版权信息（如GPL）以及版本历史记录。

我经常评论我的进口，如果进口的原因不明显，特别是如果整体计划似乎不需要进口。

我为每个类，方法或函数添加了一个docstring，描述了该块的用途以及我认为必要的任何其他信息。

我通常对相关的部分有一个分界线，例如：小部件创建，变量等。由于我在编程环境中使用SPE，它会自动突出显示这些部分，使导航更容易。

我在编码时添加了TODO评论作为提醒。这是一种很好的方法来提醒自己在验证代码正常工作后重构代码。

最后，我评论可能需要澄清的个别行，或者为将来或其他程序员需要一些元数据。

就个人而言，我讨厌查看代码并试图弄清楚它应该做什么。如果有人可以写一个简单的句子来解释它，生活会更容易。在我的书中，自我记录代码是用词不当。

Answer 14

我专注于为什么。因为什么通常很容易阅读。 TODO也很棒，他们节省了很多时间。

我记录了界面（例如文件格式）。

Answer 15

仅限预选;陈述一个班级的单一责任，任何注释或评论，以及更改日志。至于方法，如果任何方法需要实质性的评论，那么现在是重构的时候了。

Answer 16

当您撰写评论时，请停止，反思并问自己是否可以更改代码，以便不需要评论。你能改变一些变量，类或方法名称以使事情更清楚吗？某些assert或其他错误检查是否会编纂您的意图或期望？你能将一些长段代码拆分成明确命名的方法或函数吗？评论通常反映了我们无法清楚地写下（a-hem，代码）。用计算机语言写清楚并不总是那么容易，但要花一些时间去尝试...因为代码永远不会存在。

P.S。你在“硬规则”周围使用引号这一事实就说明了这一点。未强制执行的规则不是“硬规则”，而且强制执行的唯一规则是代码。

Answer 17

我在一段代码中添加了1条评论，总结了我在做什么。这有助于寻找特定功能或代码段的人。

我评论任何复杂的算法或过程，乍一看都无法解决。

我签署了我的代码。

Answer 18

我留下评论的唯一保证地点： TODO 部分。跟踪需要重新加工的东西的最佳位置就在代码中。

Answer 19

在我看来，TODO / TBD / FIXME等可以使用当前正在处理的代码，但是当你看到5年内未被触及的代码并且已经充满了它们时，你意识到这是确保事情得到解决的一种非常糟糕的方式。简而言之，评论中的TODO注释往往会留在那里。如果你有需要在某些时候修复的东西，最好使用bugtracker。

Hudson（CI服务器）有一个很棒的插件，可以扫描TODO并记录代码中有多少个。您甚至可以设置阈值，如果存在太多，则会导致构建被归类为不稳定。

我最喜欢的关于评论的经验法则是：如果代码和评论不一致，那么两者都可能不正确

Answer 20

检查标题文档（或者在方法声明之前称之为块的任何内容）时检查的一个非常重要的事情是指令和警告很容易被发现。

指令是影响客户端的任何“do”或“do do do”指令：不要从UI线程调用，不要在性能关键代码中使用，在Y之前调用X，在使用后释放返回值等等。

警告可能是一个令人讨厌的惊喜：剩下的行动项目，已知的假设和限制等等。

当你专注于你正在编写和检查的方法时，你会看到一切。当程序员在一小时内使用您的方法和其他三十三个人时，您不能指望彻底阅读。如果您有兴趣，我可以向您发送研究数据。

Answer 21

我们写了一篇关于评论的文章（实际上，我已经完成了几篇）： http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html

这很简单：编写注释是为了告诉你代码不能用的东西。

这导致一个简单的过程： - 首先写下你想要的任何评论。 - 改进代码，使评论变得多余 - 删除现在多余的评论。 - 只提交没有冗余注释的代码

Answer 22

我正在写一篇 Medium 文章，我将在其中提出这个规则：当你向仓库提交更改时，每条评论都必须是以下三种类型之一：

顶部的许可证标题
文档注释（例如 Javadoc），或
TODO 条评论。

最后一种类型不应该是永久的。要么事情完成并删除 TODO 评论，或者我们认为不需要该任务并删除 TODO 评论。

关于评论代码的“硬规则”是什么？

22 个答案: