Всякий раз, когда я пишу типичную конструкцию if-else на любом языке, я думаю, что было бы лучшим способом (с точки зрения читабельности и обзора) добавить к ней комментарии. Особенно при комментировании предложения 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поскольку, согласно вашему примеру, проверяется «вид магии», а не «величие» чего-либо.

Скажи как можно больше в коде. Сохраните прозу для случаев, которые требуют большего объяснения, чем вы можете разумно написать в коде.

Попробуйте пояснительные имена переменных

Комментарии могут быть отличными, но когда это возможно, сделайте код самодокументированным. Один из способов сделать это - использовать пояснительные имена переменных. Например, а не это:

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) {
  ...
}

Просто чтобы завершить некоторые комментарии:

Правильное использование комментариев должно компенсировать нашу неспособность выразить себя в коде. Обратите внимание, что я использовал слово сбой. Я имел в виду это. Комментарии всегда неудачи. Мы должны иметь их, потому что мы не всегда можем понять, как выразить себя без них, но их использование не является поводом для празднования. ( Чистый код Роберта С. Мартина )

Кстати, я рекомендую эту книгу.

Комментарии не должны перефразировать код, но объясняют вещи, которых нет в коде (более полная картина, почему, почему альтернатива не была выбрана ...) И ваш пример комментариев - это просто: перефразировать код.

Иногда вы можете почувствовать, что в начале elseветки необходим пересказ , но это часто является признаком того, что ваша thenветвь слишком велика.

В вашем конкретном примере комментарии, вероятно, не нужны. Как отметил Калеб , если код четко написан, а переменные имеют семантические имена, если высказывания реже требуют комментариев.

Сравните ваш фрагмент с этим:

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

В этом случае вы определенно захотите использовать комментарии, чтобы описать то, что представляют x, func1 и func2 (и дать пощечину человеку, который назвал вещи по этой схеме, особенно если это был вы). Вы даже не можете сказать, $xдолжен ли он быть логическим. Но это также тот случай, когда вам не обязательно нужны комментарии, если вы можете реорганизовать и переименовать.

В общем, я люблю писать комментарии для логических блоков, которые описывают вещи, которые сам по себе код не может. Однострочные строки каждые ~ 10-20 строк, описывающие то, что выполняют следующие несколько строк на одном более высоком уровне абстракции (например, // 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

• Держите ваши условные блоки действительно короткими.
• Вызовите метод с хорошим описательным именем, если похоже, что ваш условный код будет больше, чем простая строка или две.
• Используйте хорошие описательные имена для ваших переменных.
• Убедитесь, что условное утверждение ясно в своем значении, а не запутано или долго. Используйте метод, если он помогает содержать вещи в чистоте и удобочитаемости.

Если все вышеперечисленное не сработало, добавьте очень маленький описательный комментарий перед оператором if, чтобы прояснить свое намерение. В противном случае, на самом деле не должно быть никакой необходимости комментировать.

В C ++ или C # я, как правило, не комментирую простые случаи (когда понятно, что происходит) и не использую этот стиль для комментирования окончательного варианта ...

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