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

Question

Я никогда не выбирал, как лучше всего комментировать конструкции 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 случай

или б)

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 прямо не ясен из кода, для которого обычно требуется комментарий длиной более одной строки.

или с)

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

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

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

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

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

Answer 3

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

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

Answer 4

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

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

Answer 5

Из оракула Java Документы для соглашений кодов

Одна строка комментарии для 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.
  */
}

Answer 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
    ...
    ...
}

Answer 7

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

if (blabla) {
    // here's 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();
}

и т. Д.

Answer 8

Как насчет этого стиля? Использование // комментария для полного описания оператора 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();
        ...
    }

Answer 9

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

• если комментарий ставится над остальным, он нарушает непрерывность 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|...|