37

我从来没有决定什么是最好的评论方式if-then-else结构的最佳方式，所以我从来没有标准化一致的方式来评论它们。我很欣赏任何见解。

一些选项：

一个）

if (blabla) { 
   // this comment explains what happens in the IF case
   dothis();
} else { 
  // this comment explains what happens in the ELSE case
   dosomethingelse();
}

缺点：在多个 dothis() 语句的情况下，我喜欢对主要块进行注释，在这种情况下，IF 注释是属于第一个 dothis() 块还是属于整个 IF 情况并不总是很清楚

或 b)

if (blabla) { // this comment explains what happens in the IF case
   dothis();
} else { // this comment explains what happens in the ELSE case
   dosomethingelse();
}

缺点：只适用于简短的评论。如果代码中没有直接明确 IF 和 ELSE 的情况，我通常会注释 IF-THEN-ELSE 结构，这通常需要超过一行的注释。

或 c)

// if the following happens
if (blabla) { // then do this
   dothis();
} else { // or else do this
   dosomethingelse();
}

PS：我知道“代码应该是自我解释的”，但情况并非总是如此......

4

10 回答 10

34

对我来说，上面的评论IF解释了IF声明本身。例如，如果正在测试的条件特别复杂。

IF或下方块中的注释ELSE描述了评估条件并做出选择后会发生什么。

所以像这样：

//Is this a favoured customer and do we have a promotion?
if customer.special() and monthly.hasOffer() {
  //Add discount
  invoice.addDiscount();
} 
else {
  //Add note about favoured customer scheme
  invoice.addNotes(JOIN_OUR_DISCOUNT_SCHEME);
}
于 2009-03-09T10:31:14.860 回答
8

我从来没有考虑过。我个人并在需要时将评论置于 IF 和 ELSE 语句之上。这让我很好地将关于分支语句的注释和关于代码的注释分开。

// comment about the if statement
if (expression)
{
    // comment about the code
    doSomething();
}
// comment about the else statement
else
{
    // comment about the code
    doSomethingElse();
}

我还注意到，到目前为止，我是使用“开放花括号样式”的唯一答案，这可能是对我 Pascal 时代的一种回归，尽管我确实更喜欢代码块开始和结束的视觉理由，所以我的评论风格可能不适用于“封闭的花括号样式社区。

于 2009-03-09T11:02:54.703 回答
4

我会做案例 a) 但有一点空格：

if (blabla) {
   // This explains the whole if case

   // Can comment here for specific block comments
   doThis();
} else {
   // This explains the else case

   // Same again
   doSomethingElse();
}
于 2009-03-09T10:31:56.200 回答
2

就个人而言，我发现编写不需要少量注释的代码会更好，例如“about do do x”，然后是“DoX()”。如果有必要，我宁愿写一个名为“DoXBecauseOfY”的方法，而不是写一个评论说“do x because of y”。如果稍后的重构删除了“BecauseOfY”部分，那么在if语句之前添加注释仍然更有意义，以记录整体逻辑。

当然，您需要将每个分支中的代码量减少到可以一次读取整个if语句的程度。

于 2009-03-09T11:45:47.877 回答
1

使用对你有意义的东西，我猜（除非你在一个指定评论风格的编码标准下工作）。我个人不使用 (c) ，因为它在第一个和后续案例之间不一致。我偶尔会在简短的评论中使用（b），但通常我更喜欢（a）。如果我在 if 块中注释几个子块，我可能会在 case 注释之后留下一个空行：

if (blabla) {
    // here's a comment about this case

    // comment about this bit of code
    bit_of_code();
    // comment about this other bit of code
    other_bit_of_code();
}

等等。

于 2009-03-09T10:32:34.560 回答
1 
// Not very much sure, but here is a snippet of my code

// tweak URL as per query params and hash index positions
if (hasQueryParams && hashPos > -1) {
    // both query params and hash available
    ...
    ...
} else if (hasQueryParams) {
    // only query params available
    ...
    ...
} else if (hashPos > -1) {
    // only hash available
    ...
    ...
} else {
    // neither query params nor hash available
    ...
    ...
}
于 2013-11-16T06:31:26.553 回答
1

来自 oracle java docs的代码约定

if-else 的单行注释：

if (condition) {
 /* Here is a single line comment. */
 ...
}

if-else 的单行非常简短的注释：

if (a == 2) {
   return TRUE; /* special case */
} else {
 return isprime(a); /* works only for odd a */
}

if-else 的多行注释：

if (condition) {
 /*
  * Here is a block comment.
  */
}
于 2016-02-27T09:40:39.010 回答
0

这个怎么样？在 if 关键字之后进行注释。像自然语言一样可读，只为那些真正感兴趣的人留下可能复杂的条件代码。

    if /* user is logged in */ (user && user.loggedin()) {
        ...
    } else if /* user was logged in before */ (cookies.user && sizeof(cookies.user)>0 && cookies.user.value=="foobar" && some_other_things_in_a_long_condition) {
        ...
    } else /* apparently there's no user */ {
        ...
    }
于 2020-09-24T18:42:51.280 回答
0

这种风格怎么样？ 对整个 if-else 语句描述使用注释，对内部描述使用注释。///* */我使用/* */注释是为了不与 if-else 语句的内部注释混淆。

    // Process1
    if (cond1-1) {
        /* Process1 > Process1-1 */
        Process1-1();
        // Process1-1 description...
        Process1-1();
        Process1-1();
        ... 

    } else if (cond1-2) {
        /* Process1 > Process1-2 */
        // Process1-2 description...
        Process1-2();
        Process1-2();
        Process1-2();
        ... 

        // Process1-2
        if (cond1-2-1) {
            /* Process1 > Process1-2 > Process1-2-1 */
            Process1-2-1();
            Process1-2-1();
            Process1-2-1();
            ...

        } else if (cond1-2-2) {
            /* Process1 > Process1-2 > Process1-2-2 */
            Process1-2-2();
            // Process1-2-2 description...
            Process1-2-2();
            // Process1-2-2 description...
            Process1-2-2();
            ...

        } else {
            /* Process1 > Process1-2 > Process1-2-else */
            Process1-2-else();
            Process1-2-else();
            Process1-2-else();
            ...
        }

    } else {
        /* Process1 > Process1-else */
        Process1-else();
        Process1-else();
        Process1-else();
        ...
    }
于 2016-09-05T02:17:35.477 回答
0

只是为 else 的注释位置添加缺少的答案，我认为这是代码可读性的最佳位置，原因如下：

  • 如果注释放在 else 之上，它会破坏 if-else 的连续性
  • 如果放在里面，它可以与 else 中第一个语句的注释混合


// match jth arc
if (j < Count)
{
     // arc matched
     if (arcs[j].IsBlue) List.Add(arcs[j])
}
else // all arcs were matched
{
     // check if there more arcs
     if (arcs[j + 1] != null) continue;
}

如果你折叠块看起来真的很好

// match jth arc
if (j < Count)|...|
else // all arcs were matched|...|
于 2016-04-15T08:16:36.850 回答