Где помещать комментарии в конструкцию IF THEN ELSE

Я никогда не думал о том, как лучше всего комментировать конструкции IF-THEN-ELSE, поэтому я никогда не стандартизовал их, чтобы комментировать их. Я ценю любые идеи.

Некоторые параметры:

а)

IF (blabla) { 
   // this comment explains what happens in the IF case
   dothis();
} else { 
  // this comment explains what happens in the ELSE case
   dosomethingelse();
}

Недостаток: в случае нескольких операторов dothis() мне нравится комментировать основные блоки, и в этом случае не всегда ясно, принадлежит ли IF-комментарий к первому блоку dothis() или ко всему IF случай

или b)

IF (blabla) { // this comment explains what happens in the IF case
   dothis();
} else { // this comment explains what happens in the ELSE case
   dosomethingelse();
}
Недостаток

: работает только для коротких комментариев. Я обычно комментирую конструкции IF-THEN-ELSE, если случай IF и ELSE не явствует прямо из кода, что обычно требует комментария больше одной строки.

или c)

// if the following happens
IF (blabla) { // then do this
   dothis();
} else { // or else do this
   dosomethingelse();
}

PS: Я знаю, что "код должен быть самоочевидным", но это не всегда так...

Ответы

Ответ 1

Для меня комментарий выше IF объясняет сам оператор IF. Например, если тестируемое условие является особенно сложным.

Комментарий в блоке ниже IF или ELSE описывает, что происходит после оценки условия и выбора.

Так вот так:

//Is this a favoured customer and do we have a promotion?
if customer.special() and monthly.hasOffer() {
  //Add discount
  invoice.addDiscount();
} 
else {
  //Add note about favoured customer scheme
  invoice.addNotes(JOIN_OUR_DISCOUNT_SCHEME);
}

Ответ 2

Я никогда не думал об этом; лично и по мере необходимости я поставил комментарии над заявлениями IF и ELSE. Это дает мне хорошее разделение между комментариями о операторах ветвей и комментариями о коде.

// comment about the if statement
if (expression)
{
    // comment about the code
    doSomething();
}
// comment about the else statement
else
{
    // comment about the code
    doSomethingElse();
}

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

Ответ 3

Я бы сделал случай a), но с дополнительным битом пробела:

if (blabla) {
   // This explains the whole if case

   // Can comment here for specific block comments
   doThis();
} else {
   // This explains the else case

   // Same again
   doSomethingElse();
}

Ответ 4

Лично я считаю, что лучше писать код, который не требует небольших комментариев, которые говорят "about do do x", а затем "DoX()". Если необходимо, вместо написания комментария, говорящего "делать x из-за y", я бы предпочел написать метод с именем "DoXBecauseOfY". Если позднее рефакторинг удаляет часть "FromOfY", тогда все же имеет смысл поставить комментарий перед оператором if, документируя общую логику.

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

Ответ 5

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

if (blabla) {
    // here a comment about this case

    // comment about this bit of code
    bit_of_code();
    // comment about this other bit of code
    other_bit_of_code();
}

и т.д.

Ответ 6

// Not very much sure, but here is a snippet of my code

// tweak URL as per query params and hash index positions
if (hasQueryParams && hashPos > -1) {
    // both query params and hash available
    ...
    ...
} else if (hasQueryParams) {
    // only query params available
    ...
    ...
} else if (hashPos > -1) {
    // only hash available
    ...
    ...
} else {
    // neither query params nor hash available
    ...
    ...
}

Ответ 7

Из оракула java docs для условных обозначений кода

Комментарии для отдельной строки для if-else:

if (condition) {
 /* Here is a single line comment. */
 ...
}

Одиночная строка очень коротких комментариев для if-else:

if (a == 2) {
   return TRUE; /* special case */
} else {
 return isprime(a); /* works only for odd a */
}

Многострочные комментарии для if-else:

if (condition) {
 /*
  * Here is a block comment.
  */
}

Ответ 8

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

  • если комментарий помещен над другим, он прерывает непрерывность if-else
  • Если помещать внутри него, он может смешиваться с комментарием первого выражения внутри else


// match jth arc
if (j < Count)
{
     // arc matched
     if (arcs[j].IsBlue) List.Add(arcs[j])
}
else // all arcs were matched
{
     // check if there more arcs
     if (arcs[j + 1] != null) continue;
}

Это выглядит очень хорошо, если вы разрушаете блоки

// match jth arc
if (j < Count)|...|
else // all arcs were matched|...|

Ответ 9

Как насчет этого стиля? Используя комментарий // для описания описания целого if-else, и /* */ комментарий для внутреннего описания. Я использую комментарий /* */ для того, чтобы не путать с внутренним комментарием инструкции if-else.

    // Process1
    if (cond1-1) {
        /* Process1 > Process1-1 */
        Process1-1();
        // Process1-1 description...
        Process1-1();
        Process1-1();
        ... 

    } else if (cond1-2) {
        /* Process1 > Process1-2 */
        // Process1-2 description...
        Process1-2();
        Process1-2();
        Process1-2();
        ... 

        // Process1-2
        if (cond1-2-1) {
            /* Process1 > Process1-2 > Process1-2-1 */
            Process1-2-1();
            Process1-2-1();
            Process1-2-1();
            ...

        } else if (cond1-2-2) {
            /* Process1 > Process1-2 > Process1-2-2 */
            Process1-2-2();
            // Process1-2-2 description...
            Process1-2-2();
            // Process1-2-2 description...
            Process1-2-2();
            ...

        } else {
            /* Process1 > Process1-2 > Process1-2-else */
            Process1-2-else();
            Process1-2-else();
            Process1-2-else();
            ...
        }

    } else {
        /* Process1 > Process1-else */
        Process1-else();
        Process1-else();
        Process1-else();
        ...
    }