Как следует прокомментировать структуру if-else?

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

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

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

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

bool fooIsNotReallyGood = ....;

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

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

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

Используйте условия для самостоятельного комментирования, тогда в дополнительных комментариях нет необходимости. Допустим, условием является достижение максимальной стоимости кредита. Это дает нам:

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

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

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

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

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

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

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

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

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

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

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

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

P.S. Вроде мнений столько, сколько людей :)

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

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

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

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

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

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

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

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

Вы можете извлечь 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 ветку приходится более одной строки.