Что такое хороший способ комментировать if-else-предложения? [закрыто]

15

Всякий раз, когда я пишу типичную конструкцию 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()
}

Каковы ваши лучшие примеры для комментариев?

кульминация
источник
8
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
комнат
1
Почему Биггер лучше / предпочтительнее / отличается? Видишь, я не знаю.
JeffO
Это тема для вопросов или споров? Даже если этот вопрос имеет смысл, это начало войны.
Независимо
1
Мне интересно, что так много людей чувствовали, что на этот вопрос стоит ответить, но не стоит голосовать. Хотя мне интересны ответы (мой - единственный +1), этот вопрос, кажется, является типичным примером проблемы с велосипедами.
canisrufus
1
@canisrufus Это выглядит так только потому, что отрицательные голоса компенсируют повышенные. На данный момент есть 6 голосов "за" и "4" за чистый +2.
Калеб

Ответы:

34

Я предпочитаю либо:

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поскольку, согласно вашему примеру, проверяется «вид магии», а не «величие» чего-либо.

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

Калеб
источник
13
+1 не переусердствуйте с комментариями, ясный код не требует комментариев
трещотка урод
3
@ratchetfreak Кажется, что мы в основном согласны, но комментарии часто необходимы, чтобы прояснить код. Предоставление исторического контекста, объяснение неожиданного поведения или устранение неоднозначности лучше всего делать с комментариями.
Калеб
1
Хороший вопрос, Калеб. Это правда, что код должен сам как-то автоматически комментировать, насколько это возможно.
Acme
7
Хорошие комментарии не объясняют что - «проверьте, какая магия должна произойти», - они объясняют почему, то есть «пользователи могут выбрать вид магии для запуска» или «Сервис заполнит большую магию, если они доступно, поэтому мы должны проверить тип "или что-то еще. Неважно, насколько хорош ваш код, почему неизвестен тем, кто не знаком с бизнес-правилами.
Бруно Брант
1
Беда в том, что проще всего писать трудно читаемый код, а не комментировать. Кроме того, легче писать трудно читаемый код, но комментируйте его лучше, чем последовательно писать код, настолько хороший, что он не нуждается в комментариях.
asfallows
11

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

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

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) {
  ...
}
Натан Лонг
источник
2
Я иду один шаг дальше и использовать: is_potential_elvis_impersonator. (Префикс Is / Has / etc. Для логической переменной ..)
Джейк Бергер
@jberger - мне это нравится. Редактирование ответа соответственно.
Натан Лонг
3

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

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

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

CSA
источник
3

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

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

AProgrammer
источник
2

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

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

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();
}

Я чувствую, что он самый чистый, потому что комментарий совпадает с кодом, к которому он относится. Комментарий, описывающий, что делает код, должен быть как можно ближе к комментарию, который он описывает.

asfallows
источник
2
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 #.

Джейк Бергер
источник
1

Я пытаюсь использовать комментарии внутри блока, говорящие о том, что делает этот блок (ваш первый пример).

Где это "ломается" - это при использовании 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
Дианна
источник
Да, это действительно работает лучше, когда вы используете язык без скобок.
Acme
1
  • Держите ваши условные блоки действительно короткими.
  • Вызовите метод с хорошим описательным именем, если похоже, что ваш условный код будет больше, чем простая строка или две.
  • Используйте хорошие описательные имена для ваших переменных.
  • Убедитесь, что условное утверждение ясно в своем значении, а не запутано или долго. Используйте метод, если он помогает содержать вещи в чистоте и удобочитаемости.

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

S.Robins
источник
0

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

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}
dodgy_coder
источник
4
Или лучше "pattern.doSomething ()" и пусть ОО сделает свою работу.
Пол Томблин