if-then-else 结构中的注释应该放在哪里？ [关闭]

Posted 2023-02-21

【中文标题】if-then-else 结构中的注释应该放在哪里？ [关闭]

【英文标题】：Where to put comments in an if-then-else construct? [closed]

【发布时间】：2010-10-12 03:51:59

【问题描述】：

我从未决定评论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();

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

或 c)

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

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

【问题讨论】：

评论应该解释原因，而不是正在发生的事情。如果发生的事情不清楚 - 您需要修复它，也许将条件转出一个可以逐步分解的函数。

【参考方案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);

【讨论】：

你知道那些 cmets 并没有真正为可读性做任何事情，对吧？

@pzycoman：你知道这是关于风格的讨论，而不是内容，对吧？您也知道 cmets 确实可以提高可读性，对吧？

【参考方案2】：

我从来没有认真考虑过；就个人而言，当需要时，我已将 cmets 置于 IF 和 ELSE 语句之上。这让我很好地将关于分支语句的 cmets 和关于代码的 cmets 区分开来。

// comment about the if statement
if (expression)

    // comment about the code
    doSomething();

// comment about the else statement
else

    // comment about the code
    doSomethingElse();

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

【讨论】：

您对 else 语句有何评论？通常它们是不言自明的。 :-)

如果一个分支在函数的输出上，它可能需要一些解释，一个更好的例子可能是 elseif。

如果不需要对其中一个或另一个进行评论，请忽略该评论。这就像函数开始时的样板；如果在某个标题下没有什么可说的，请省略该标题。 （我不提倡按功能使用样板；我看到的大部分内容都已过时且错误！）

如果 else 看起来不太可能，但由于某些极端情况它不是？

【参考方案3】：

我会做 case 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();

【参考方案4】：

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

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

【参考方案5】：

我猜，使用对您有意义的东西（除非您使用的编码标准指定了评论风格）。我个人不使用 (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();

等等。

【参考方案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
    ...
    ...

【参考方案7】：

来自 oracle java docs 的代码约定

单行 if-else 的 cmets：

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

单行很短 if-else 的 cmets：

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

多行 if-else 的 cmets：

if (condition) 
 /*
  * Here is a block comment.
  */

【参考方案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|...|

【参考方案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();
        ...
    

【参考方案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 */ 
        ...