Всякий раз, когда я пишу типичную конструкцию 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()
}
Каковы ваши лучшие примеры для комментариев?
else { // for future reader: sorry, at the moment of writing this I did not have time and skills to come up with a better way to express my logic
Ответы:
Я предпочитаю либо:
или:
Кажется немного глупым писать комментарий, объясняющий то, что проверяет ваше условие, если код явно не указывает это. Даже тогда лучше переписать код, чтобы сделать его максимально понятным. То же самое относится и к телам условных блоков - если вы можете сделать причину для чего-то очевидного, сделайте это вместо комментариев.
Я не поддерживаю философию «никогда не писать комментарии», но я верю в то, чтобы избегать комментариев, которые говорят, что код должен говорить. Если вы напишете комментарий типа «проверьте, какое волшебство должно произойти», когда код может сказать
if ($magic == big) {...
, читатели перестанут читать ваши комментарии очень быстро. Использование меньшего количества более значимых комментариев придает каждому из ваших комментариев большую ценность, и читатели гораздо чаще обращают внимание на те, которые вы пишете.Выбор значимых имен для ваших переменных и функций важен. Правильно выбранное имя может устранить необходимость в пояснительных комментариях по всему коду. В вашем примере,
$magic
или, может быть, вам$kindOfMagic
кажется, что это лучшее имя, чем,$big
поскольку, согласно вашему примеру, проверяется «вид магии», а не «величие» чего-либо.Скажи как можно больше в коде. Сохраните прозу для случаев, которые требуют большего объяснения, чем вы можете разумно написать в коде.
источник
Попробуйте пояснительные имена переменных
Комментарии могут быть отличными, но когда это возможно, сделайте код самодокументированным. Один из способов сделать это - использовать пояснительные имена переменных. Например, а не это:
Я бы предпочел именованную переменную:
источник
is_potential_elvis_impersonator
. (Префикс Is / Has / etc. Для логической переменной ..)Просто чтобы завершить некоторые комментарии:
Кстати, я рекомендую эту книгу.
источник
Комментарии не должны перефразировать код, но объясняют вещи, которых нет в коде (более полная картина, почему, почему альтернатива не была выбрана ...) И ваш пример комментариев - это просто: перефразировать код.
Иногда вы можете почувствовать, что в начале
else
ветки необходим пересказ , но это часто является признаком того, что вашаthen
ветвь слишком велика.источник
В вашем конкретном примере комментарии, вероятно, не нужны. Как отметил Калеб , если код четко написан, а переменные имеют семантические имена, если высказывания реже требуют комментариев.
Сравните ваш фрагмент с этим:
В этом случае вы определенно захотите использовать комментарии, чтобы описать то, что представляют x, func1 и func2 (и дать пощечину человеку, который назвал вещи по этой схеме, особенно если это был вы). Вы даже не можете сказать,
$x
должен ли он быть логическим. Но это также тот случай, когда вам не обязательно нужны комментарии, если вы можете реорганизовать и переименовать.В общем, я люблю писать комментарии для логических блоков, которые описывают вещи, которые сам по себе код не может. Однострочные строки каждые ~ 10-20 строк, описывающие то, что выполняют следующие несколько строк на одном более высоком уровне абстракции (например,
// Make the right amount of magic happen
для вашего примера), помогут вам ориентироваться и дать новому рецензенту понимание того, что вы делаете и когда ,На самом деле я часто пишу эти однострочники перед тем, как начать писать код, чтобы не потерять поток, который должен иметь сегмент.
Наконец, если вы действительно предпочитаете (или есть мандат, который требует) комментариев в блоке if независимо от читабельности кода, я рекомендую:
Я чувствую, что он самый чистый, потому что комментарий совпадает с кодом, к которому он относится. Комментарий, описывающий, что делает код, должен быть как можно ближе к комментарию, который он описывает.
источник
Я держу свои скобки выровненными и помещаю это прямо после скобки.
[Condition] -> [pseudo-code]
С другой стороны, это технически означает, что все остальные условия не выполнены, поэтому я обычно использую скобки.
([Condition]) -> [pseudo-code]
Примечание: это для C #.
источник
Я пытаюсь использовать комментарии внутри блока, говорящие о том, что делает этот блок (ваш первый пример).
Где это "ломается" - это при использовании
elseif
. Я использую Basic, чтобы не было явного конечного блока, и часто приходится комментировать, что проверяет условие, которое идет в строке выше (конечно, с разрывом строки), если оно слишком длинное.источник
Если все вышеперечисленное не сработало, добавьте очень маленький описательный комментарий перед оператором if, чтобы прояснить свое намерение. В противном случае, на самом деле не должно быть никакой необходимости комментировать.
источник
В C ++ или C # я, как правило, не комментирую простые случаи (когда понятно, что происходит) и не использую этот стиль для комментирования окончательного варианта ...
источник