Question

我从未决定评论if-then-else构造的最佳方式，因此我从未标准化以一致的方式对它们进行评论。我很欣赏任何见解。

一些选项：

A）

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-comment是属于第一个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：我知道“代码应该是自我解释的”，但情况并非总是如此......

Answer 1

对我而言，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);
}

Answer 2

我从来没有想过这么想;我个人并在需要时将注释放在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();
}

我还注意到，到目前为止，我是唯一一个使用“开放大括号样式”的答案，这可能是我帕斯卡日的回归，虽然我更喜欢代码块的开头和结尾的视觉证明，所以我的评论风格可能不适用于“封闭的大括号式社区。

Answer 3

我会做案例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();
}

Answer 4

就我个人而言，我发现编写代码时不需要太多评论说“关于do do x”，然后是“DoX（）”。如果有必要，我宁愿写一个名为“DoXBecauseOfY”的方法，而不是写一条评论“因为y而做x”。如果后来的重构删除了“BecauseOfY”部分，那么在 if 语句之前添加注释仍然更有意义，记录整体逻辑。

当然，您需要将每个分支中的代码量减少到可以立即读取整个 if 语句的位置。

Answer 5

使用对你来说有意义的东西，我想（除非你是在一个指定评论风格的编码标准下工作）。我个人不使用（c）因为它在第一个和下面的情况之间不一致。我偶尔会使用（b）当一个简短的评论会做，但一般我更喜欢（a）。如果我在if块中评论几个子块，我可能会在案例评论后留下一个空行：

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();
}

等等。

Answer 6

// 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
    ...
    ...
}

Answer 7

从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.
  */
}

Answer 8

只是为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|...|

Answer 9

这种风格怎么样？ 对整个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();
        ...
    }

Answer 10

这个怎么样？ 在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 */ {
        ...
    }

在if-then-else结构中放置注释的位置？

10 个答案: