Как следует прокомментировать структуру 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. Я не спрашиваю о реорганизации этих двух строк кода, только о стиле кода и форматировании комментариев.

ОТВЕТЫ

Ответ 1

Если необходимо прокомментировать 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;
}

Ответ 2

Другой вариант:

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

Ответ 3

Вы должны только комментировать, если код не является самоочевидным. Так что сделайте, если я объясню. Как это возможно

bool fooIsNotReallyGood = ....;

if(fooIsNotReallyGood) {
...
} else {
...
}

Ответ 4

Если код уже не является самодокументированным, я бы структурировал его следующим образом:

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 или так.

Ответ 5

Переходите к условиям самокомментации, тогда дополнительные комментарии не нужны. Предположим, что условие заключается в том, что максимальный кредит в стоимости достигнут. Это дает нам:

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

Не нужно указывать, когда я = 2, что максимальная сумма кредита не была достигнута, поскольку это самообучение. В стороне, я также переименовал бы i в нечто более значимое.

Ответ 6

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

Ответ 7

//condition isn't met кажется бесполезным комментарием. Но в случае, когда такой комментарий требуется, я делаю это так (С#):

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

Однако, если блок является только if-else, я бы объединил оба комментария раньше, если.

Для javascript я предпочитаю

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

P.S. Кажется, существует столько мнений, сколько есть людей:)

Ответ 8

Вот как я делаю свои комментарии для if then statement, хотя обычно я считаю, что это не нужно. Мне нравится вставлять его в соответствие с if/else и вставлять вкладку в одно и то же место

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

Ответ 9

Переменные важны, а не сами условия.

if condition: # <condition dependent variable> was <predicated>
  dosomething()
elif othercondition: # <othercondition dependent variable> <predicated>
  dootherthing()
else: # <all variables> <not predicated>
  doelsething()

Ответ 10

Нет единого ответа - у разных людей будут разные мнения о том, что наиболее читаемо. Тем не менее, я думаю, что есть согласие, что комментарии должны действительно добавить ценность для (в противном случае самоочевидного) кода и что стиль комментариев должен быть согласованным.

То, как я обрабатываю комментарии для не сразу понятных условий, выглядит следующим образом:

  // 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)

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

Ответ 11

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

В простых случаях комментарии отвлекают от кода. Но, предполагая более сложное условие, я предпочитаю:

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

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

Ответ 12

Вы можете извлечь код if-else в методы и правильно их назвать:

function main() {
  checkForCondition(condition);
  conditionIsNotMet(condition);
}

function checkForCondition(boolean condition) {
  if (condition) {
    i = 1;
  }
}

function conditionIsNotMet(boolean condition) {
  if (!condition) {
    i = 2;
  }
}

В таком тривиальном случае это кажется излишним, но представьте, что имеет более одной строки на ветвь if-else.