web-dev-qa-db-ja.com

if-else構造をどのようにコメントする必要がありますか？

あなたが持っているとしましょう：

if(condition) {
    i = 1;
} else {
    i = 2;
}

また、ifおよびelseブロックを説明するコメントを追加する必要があります。誰かが一目で簡単に手に入れることができるようにする最も読みやすい方法は何ですか？

私は通常このようにします：

//check for condition
if(condition) {
    i = 1;
} else {
    //condition isn't met
    i = 2;
}

コメントが異なるレベルにあるので十分ではないので、一目でifコメントを選択すると、elseコメントは内部構造に属しているように見えます。

次のように配置します。

if(condition) {
    //check for condition
    i = 1;
} else {
    //condition isn't met
    i = 2;
}

構造全体がコメントされていないように見えるため、私にとっても見栄えがよくありません（条件が大きく、複数の行をとる場合があります）。

そんな感じ：

//check for condition
if(condition) {
    i = 1;
//condition isn't met
} else {
    i = 2;
}

コメントの観点からはおそらく最高のスタイルですが、コード構造としては紛らわしいでしょう。

そのようなブロックをどのようにコメントしますか？

PS。この2行のコードをリファクタリングするのではなく、コードのスタイルとコメントの書式設定のみを求めています。

coding-stylecomments
65
serg

If elseステートメントをコメントする必要がある場合は、コードがそのポイントに到達した原因を説明することを好みます。特に、循環的複雑度が高いコードでは

if (condition) { 
// User is taking a course at college x:
    i = 1;
} else { 
// User is not taking any course at college x:
    i = 2;
}
31
MrBliss

別のオプションは次のとおりです。

if(condition) { //check for condition
    i = 1;
} else { //condition isn't met
    i = 2;
}
23
David Johnstone

コードが自明でない場合にのみ注釈を付ける必要があります。だから、もしも自明なら。おそらくこのように

bool fooIsNotReallyGood = ....;

if(fooIsNotReallyGood) {
...
} else {
...
}
13
Preet Sangha

コードがまだ自己文書化されていない場合、次のように構成します。

if (someCondition) {
    // If some condition, then do stuff 1.
    doStuff1();
}
else {
    // Else do stuff 2.
    doStuff2();
}

ただし、コードが既に自己文書化されている場合は、あまり意味がありません。次のような複雑な条件のためにコメントを追加したい場合：

if (x == null || x.startsWith("foo") || x.endsWith("bar") || x.equals("baz")) {
    doStuff1();
}
else {
    doStuff2();
}

次に、次のようにリファクタリングすることを検討します。

boolean someCondition = (x == null || x.startsWith("foo") || x.endsWith("baz") || x.equals("waa");

if (someCondition) {
    doStuff1();
} else {
    doStuff2();
}

ここで、変数名someCondition実際には、条件全体を一言で要約します。例えば。 usernameIsValid、userIsAllowedToLoginなど。

10
BalusC

自己コメントの条件に進み、追加のコメントは必要ありません。条件は、最大貸付額に達したということです。これにより、次のことができます。

if (maximumLoanToValueIsReached)
{
   i=1;
}
else
{
   i=2;
}

I = 2の場合、最大融資額に達していないことを自明であると指定する必要はありません。余談ですが、iの名前をより意味のあるものに変更します。

5
Chris Knight

これらの特定の場合にはコメントしません。コメントは、すでに明確なコードに価値を追加するものではありません。読みにくい非常に複雑な条件がある場合は、それを非常にクリーンな名前の関数（おそらくinline）に分解することを検討します。

4
sblom

//condition isn't metは無意味なコメントのようです。しかし、そのようなコメントが必要な場合は、次のようにします（C＃）：

//check for condition
if(condition) 
{
    i = 1;
} 
//some other condition
else 
{
    i = 2;
}

ただし、ブロックがif-elseの場合、ifの前に両方のコメントをマージするよりも。

JavaScriptの場合

//check for condition
if(condition) {
    i = 1;
} else { //some other condition
    i = 2;
}

追伸人々と同じくらい多くの意見があるようです:)

2
Egor Pavlikhin

これがif thenステートメントのコメントの書き方です。通常は必要ではないと思います。 if/elseに合わせて、同じ場所にタブで移動するのが好きです

if ( condition )    //if above the bar
{
    i = 0;
    k = 1;
}
else                //else if below
{
    i = 1;
    k = 2;
}
2
Justen

コメントは非常に個人的なものであり、（以前の回答の一部でわかるように）コードと同じくらい多くの議論を生み出します。

単純な場合、コメントはコードを損ないます。しかし、より複雑な条件を想定して、私は好む：

/*
** Comment explaining what the condition
** is trying to determine
*/
if ( condition )
{
    /*
    ** Comment explaining the implications
    ** of the condition being met
    */
    do_something();
}
else
{
    /*
    ** Comment explaining the implications
    ** of the condition not being met
    */
    do_something_else();
}

いずれにしても、コメントはコードを繰り返すだけではいけません。

1
Andrew

変数は重要であり、条件そのものではありません。

if condition: # <condition dependent variable> was <predicated>
  dosomething()
Elif othercondition: # <othercondition dependent variable> <predicated>
  dootherthing()
else: # <all variables> <not predicated>
  doelsething()
1
Ignacio Vazquez-Abrams

単一の答えはありません。most可読性については、人によって意見が異なります。しかし、コメントは実際には（それ以外の場合は自明の）コードに価値を追加する必要があり、コメントスタイルは一貫している必要があるという点で一致していると思います。

すぐに説明できない状況に対するコメントの処理方法は次のとおりです。

  // If the condition for a local tree imbalance is met,
  // juggle the immediate nodes to re-establish the balance.
  // Otherwise, execute a global balancing pass.
  if ( somewhat muddled condition )
  {
     ...code...
  }
  else // Tree is in local balance
  {
     ... more code...

  } // if/else (tree locally imbalanced)

最後の「}」に対するコメントは、主に条件の終わりに視覚的な重みを与え、ソースを読みやすくするために存在します。

1
Lars