どの言語でも典型的なif-else-constructを書いているときはいつでも、コメントを追加するための（読みやすさと概要の点で）最良の方法は何だろうと思います。特にelse節にコメントするとき、コメントはいつも私にとっては場違いな感じがします。次のようなコンストラクトがあるとします（例はPHPで記述されています）。

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

次のようにコメントできます。

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

または

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

または

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

これにコメントするためのベストプラクティスの例は何ですか？

私はどちらかを好む：

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

または：

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

コードに明確に記述されていない限り、条件がチェックする内容を説明するコメントを書くのは少しばかげているようです。それでも、可能な限り明確にするためにコードを書き直した方が良いでしょう。条件ブロックの本体についても同じことが言えます。何かを明らかにする理由を説明できる場合は、コメントする代わりにそれを行います。

私は「コメントを書くことは絶対にしない」という哲学を購読していませんが、コードが言っているべきことを言っているコメントを避けることを信じています。コードが言うことができるときに「どんな種類の魔法が起こるかを確認する」のようなコメントを書くとif ($magic == big) {...、読者はあなたのコメントを非常に早く読むのをやめます。より少ない、より意味のあるコメントを使用すると、各コメントの価値が高まり、読者は自分が書いたコメントに注意を払う可能性が高くなります。

変数と関数に意味のある名前を選択することが重要です。適切に選択された名前を使用すると、コード全体で説明のコメントが不要になります。あなたの例では、$magicまたはおそらくあなたの例によると、それは何かの「大きさ」ではなく、テストされている「魔法の種類」$kindOfMagicである$bigため、より良い名前のようです。

コードでできる限り多くのことを言ってください。合理的にコードを書くよりも多くの説明が必要な場合は、散文を保存してください。

説明変数名を試す

コメントは素晴らしいものですが、可能であれば、コードを自己文書化します。これを行う1つの方法は、説明変数名を使用することです。たとえば、これではなく：

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

私は名前付き変数を好む：

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

いくつかコメントを記入してください：

コメントの適切な使用は、コードで自分自身を表現できないことを補うためです。失敗という言葉を使用したことに注意してください。本気で言っているんだ。コメントは常に失敗です。私たちは彼らなしで自分を表現する方法を常に理解することはできないので、彼らを持たなければなりませんが、彼らの使用はお祝いの原因ではありません。（Robert C. MartinによるClean Code）

ところで：私はこの本をお勧めします。

コメントはコードを言い換えるべきではありませんが、コードに含まれていないことを説明します（全体像、理由、代替案が選ばれなかった理由など）。

elseブランチの開始時に言い換えが必要であると感じることもありますが、それは多くの場合、thenブランチが大きすぎることを示しています。

具体的な例では、コメントはおそらく必要ありません。以下のようカレブが挙げコードが明確に書かれている場合、およびステートメントはコメント必要とする可能性が低い場合の変数は、意味の名前を持ちます。

スニペットをこれと比較してください：

if ($x) {
    func1();
} else {
    func2();
}

この場合、コメントを使用して、x、func1、およびfunc2が何を表すのかを明確に説明する必要があります（特に、そのスキームで名前を付けた人を平手打ちします）。$xブール値であるかどうかを見分けることさえできません。ただし、これは、リファクタリングと名前変更が可能な場合、必ずしもコメントを必要としない場合です。

一般に、私はコードがそれ自体ではできないことを説明する論理ブロックのコメントを書くのが好きです。10〜20行ごとに1行のライナーを使用すると、次の少数の行が1つのより高い抽象化レベル（たとえば// Make the right amount of magic happen、例）で何を達成するかを説明し、方向性を保ち、何をしているのかを新しいレビュー担当者に洞察を与えるのに役立ちます。

私は実際にコードを書き始める前にこれらのワンライナーを頻繁に書くので、セグメントが持つはずのフローを追跡できません。

最後に、コードの読みやすさに関係なく、ifブロック内のコメント句を本当に好む（または必要とする命令がある）場合は、以下をお勧めします。

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

コメントが関連するコードと並んでいるので、私はそれが一番きれいだと感じています。コードの実行内容を説明するコメントは、説明するコメントにできるだけ近づける必要があります。

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

ブラケットを並べて、ブラケットの直後に配置します。

[Condition] -> [pseudo-code]

他では、技術的には他のすべての条件が失敗したことを意味するため、通常は括弧を使用します。

([Condition]) -> [pseudo-code]

注：これはC＃用です。

ブロック内でコメントを使用して、そのブロックが何をするのかを説明します（最初のサンプル）。

この種類が壊れるのは、を使用する場合elseifです。Basicを使用しているので、明示的な終了ブロックはなく、長すぎる場合は（もちろん改行を使用して）上の行に行く条件を確認する必要があることをコメントする必要があります。

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• 条件ブロックは本当に短くしてください。
• 条件付きコードが単純な1行または2行以上になると思われる場合は、わかりやすい名前でメソッドを呼び出します。
• 変数にはわかりやすい名前を使用してください。
• 条件文がその意味において明確であり、難読化されていないか、長くないことを確認してください。物事を整理して読みやすくするのに役立つ場合は、メソッドを使用します。

上記のすべてが失敗する場合は、ifステートメントの前に非常に小さな説明コメントを追加して、意図を明確にします。そうでなければ、本当にコメントする必要はないはずです。

C ++またはC＃では、単純なケース（何が起こっているのかが明確な場合）をコメントしないのが普通です。

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}