Question

我正在尝试让未来的读者轻松理解我的代码。

我总是遇到如何用if语句注释来说明它是最容易理解的问题。

也许这看似微不足道，但这总是困扰着我

以下是一个例子：

if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

以下是我可以考虑评论它的一些方法

// If request doesn't exist
if ( !$request ) {
    // Set request to current request_uri
    $request = $_SERVER['REQUEST_URI'];
}

// Check for a request
if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

// Request doesn't exist
if ( !$request ) {
    // Set request
    $request = $_SERVER['REQUEST_URI'];
}

不是最好的例子，但我看到它的方式有无限的方式来表达它。

我从来没有真正在团队中工作，所以我对其他人阅读我的代码没有多少经验。

您有什么经验可以说明这一点，以使其对未来的程序员具有可读性。

Answer 1

对于您提供的案例，我根本不会发表评论。在执行非常棘手或非显而易见的事情时，我只在方法/函数体中使用注释 - 我试图避免两件事。只需在方法的开头加上一条简短的评论。

Answer 2

在这个特定的例子中，我不打算评论if语句 - 你正在重复代码中所说的内容。

我可能会看到测试代码很复杂的情况：

if (a == 3 && b && c > 2)

但在这种情况下，我会首先尝试提取一个有意义名称的方法：

if (markerIsValid(a, b, c))

只有在不可能的情况下才会对测试进行评论。

Answer 3

我的建议是'不要陈述明显的'。

读取if（！$ request）是否说 - 如果没有请求。我不需要对此发表评论。

如果你有多个检查（这个||（＆amp;＆amp; this-too）），我会去创建一个返回带有结果的布尔值的方法。然后你的方法名称是你的评论，通常比实际评论更好。

Answer 4

我不想说这没关系，但这主要取决于程序员的偏好。更好的方法是在if语句中编写谓词，使其无需评论即可读取。

但是，某些语言比其他语言更容易。例如，某些语言使用语义否定关键字，如not，这可以使谓词更容易阅读。话虽这么说，如果有问题的读者是一个体面的程序员，他们应该能够处理一般测试的逻辑，而不必手动注释。

底线：自行决定。

Answer 5

使用您的示例，我通常更喜欢以下样式：

if ( !$request ) {
    // The request is not yet set, so retrieve it.
    $request = $_SERVER['REQUEST_URI'];
}

我喜欢将其放在if块内，以便在有else或else if时让它看起来更好。

if ( !$request ) {
    // The request is not yet set, so retrieve it.
    $request = $_SERVER['REQUEST_URI'];
}
else {
    // Comment about doing something else here.
}

Answer 6

请记住：您很少需要内联评论来说明代码正在做什么;除非你在解释一个特别粗糙的算法，否则代码应该自己承担这个负担，而不需要评论。（如果不能，您可能需要使您的变量名更具描述性。）

然而，解释为什么代码正在做它正在做的事情的评论可能非常有价值。（假设它不是很明显;如果是，请跳过评论。）

在那之后，这确实是个人品味的问题，尽管我提倡一致性。就个人而言，当我评论“if”树时，我更倾向于将评论缩进到与他们解释的条款一致：


    if ( !$request ) {
        // If the request isn't set, foo() will barf; the current
        // request is a suitable default.
        $request = $_SERVER['REQUEST_URI'];
    }

只要确保你的评论证明他们自己的存在是合理的，其余的就是肉汁。

Answer 7

当我编写代码注释时，我尝试

解释一个棘手的，非显而易见的程序（reg ex是一个完美的例子），或
解释为什么我正在做我正在做的事情。

结帐Code Complete。麦康奈尔在评论方面有很好的篇章。

我会为每个编写代码的人推荐这本书。

Answer 8

阅读Robert Martin的书“清洁代码”。

http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

注释应仅用于解释代码无法解释的概念。

Answer 9

我对Code Complete的引用是第二本：这本书应该是程序员必读的优秀书籍。

我会记住一些事情：

不要重复代码：解释一般情况下的内容。
永远不要假设某些事情是显而易见的;澄清并解释代码。
使用函数明确说明您的含义：将名称与正在进行的操作相关联。
永远不要认为代码是不言自明的 - 即使它应该是。最重要的是，永远不要认为特定代码“成语”将由理解它的人阅读：解释代码正在做什么。

正如有人所说，如果可以的话，不要带负面线：我有一个编程课，在任何情况下都不允许使用负IF。如果真的卡住了，您可以使用您的母语（例如英语）。而不是：

if (!eof(f))

可以说：

if (moreData(f))

用你的例子，我会用这样的东西（如果我理解正确的话）：

// Make sure that we have a valid request:
// set it if it is not set already
if ( !$request ) {
    $request = $_SERVER['REQUEST_URI'];
}

我还要补充：不要在框中添加评论。一个“盒子”很难维持和保持：一个人花费更多的时间修复“盒子”而不是保持评论的最新状态。

Answer 10

你不应该这样做。只需通过引入解释变量重构：

 if ( (platform.toUpperCase().indexOf("MAC") > -1) &&
      (browser.toUpperCase().indexOf("IE") > -1) &&
       wasInitialized() && resize > 0 )
 {
   // do something
 }

变为：

boolean isMacOs     = platform.toUpperCase().indexOf("MAC") > -1;
boolean isIEBrowser = browser.toUpperCase().indexOf("IE")  > -1;
boolean wasResized  = resize > 0;

if (isMacOs && isIEBrowser && wasInitialized() && wasResized)
{
    // do something
}

Answer 11

我使用这种形式：

// Full Comment
if (condition) {
    action;
    action;
}

因为在启用代码折叠时，您最终得到的内容如下所示：

// Full Comment
if (condition) { ...} [+]

而不是：

// Half Comment
if (condition) { ...} [+] <---button to click to get the rest of the comment

Answer 12

这非常取决于程序员。我将提供两个提示：

请勿说明显而易见的

采用以下示例：

// If request doesn't exist
if ( !$request ) {

在上面的例子中，评论只是复制了代码（我意识到这是一个例子，但我仍然想说明这一点）。重点评论澄清代码中可能不明显的内容。另一方面......

不要假设所有开发者都知道您的知识

看看你的代码并想象你是一个相对初学者。你明白吗？如果没有，请通过评论澄清。

Answer 13

我不喜欢阅读带有评论的代码。代码应该易于理解。我通常只评论大而难以理解的代码部分，而不是个别和琐碎的行。

Answer 14

除非您的受众群体是初学者（1）。

Answer 15

我更专注于使代码本身尽可能自我记录，这意味着良好的变量名称，函数名称等等。对于函数或代码块而言，注释比单独的行更好。

Answer 16

评论应该解释不清楚的代码。在大多数情况下，应该重写不清楚的代码以使其清晰。在您的示例中，我认为根本不需要评论。所以可以回答如何说出你的意见是专注于使代码更具可读性，因此你不需要评论。

当它们是必要的时候，它们不应该只是伪代码，而应该提供读者没有立即可用的信息。一个例子可能是“新”语句的注释，指示释放内存的位置。

Answer 17

我同意Evan - 写你的代码是可读的。假设你有复杂的代码需要注释，我使用并优先选择第一个选项，它可以作为可读文本使用。

Answer 18

如果您的变量名称很好，那么if语句应该是非常自我解释的。

此外，通过使用一些“战略性”评论，它应该都是普通英语。

在此文档http://www.doc.ic.ac.uk/lab/cplus/c++.rules/chap4.html#sect3

中查看“战术”和“战略”评论的定义

Answer 19

我同意neil，对于那个例子，无论如何，你很明显你正在检查一个请求是否不存在。放入许多注释可能会使代码的可读性降低。（即评论每行或每隔一行代码）

Answer 20

查看类似/相同的问题：Where to put comments in an IF THEN ELSE construct

Answer 21

以一种评论方式命名您的变量/方法。

如果你的if中有很多复杂的条件，那么将这个条件提取到一个布尔函数/方法，清楚地解释它正在做什么。

如果您需要评论您的条件，那么您可能正在前往Arrow Anti-pattern。

使用composed method refactoring来帮助解决此问题。确保您的方法/函数封装在相同的抽象级别。多态性将允许你完全摆脱条件。它更好，因为行为是在运行时动态确定的。你需要编写（和维护）的东西少一点。

Answer 22

如前所述，也许你的例子有点过于简单，以便真正对它有相关的评论，但这里有几个一般的建议：

通常更容易阅读“积极”条件而不是否定（不是条件）
毫不犹豫地提取具有详细名称的方法，该方法将传达意图并因此避免某些评论的需要。在你的情况下，说你创建：
```
function getRequest( $req ) {
    if( isset( $req ) ) {
        return $req;
    } else {
        return $_SERVER['REQUEST_URI'];
    }
}
```
但同样，我们需要一个更合适的例子，在你的情况下它可能有点矫枉过正
必读：

Answer 23

我意识到它不适用于你的具体例子，但作为一个学究者，我不得不说：只要有可能，不要带负面情况。无论评论是什么，都难以阅读。一般来说，我同意测试应该在没有评论的情况下清楚，或者您可能希望将其提取为有意义的方法。

Answer 24

示例if语句很简单，不保证任何评论。过度评论可能很危险，因为您不仅要维护代码而且还要维护评论。对于复杂的if语句，你有正确的想法 - 在if语句的正上方添加注释。

如何对if语句最具可读性发表评论

24 个答案: