Кожного разу, коли я пишу типову конструкцію if-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()
}

Які ваші приклади найкращої практики для коментування цього?

Я вважаю за краще:

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тому, що згідно з вашим прикладом, це "магія", яку випробовують, а не "велич" чогось.

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

Спробуйте пояснювальні назви змінних

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

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) {
  ...
}

Просто для завершення деяких коментарів:

Правильне використання коментарів - це компенсувати наше неспроможність висловити себе в коді. Зауважте, що я використав слово "провал". Я мав це на увазі. Коментарі - це завжди невдачі. Ми повинні їх мати, тому що ми не завжди можемо зрозуміти, як висловити себе без них, але їх використання не є причиною для святкування. ( Чистий кодекс Роберта К. Мартіна )

До речі: я рекомендую цю книгу.

Коментарі не повинні перефразовувати код, але пояснюють речі, які відсутні в коді (детальна картина, чому, чому не обрана альтернатива ...) І ваш приклад коментарів - це саме так: перефразовування коду.

Іноді ви можете відчути, що парафраза потрібна на початку elseгілки, але це часто ознака того, що ваша thenгілка занадто велика.

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

Порівняйте ваш фрагмент із цим:

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

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

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 #.

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

Там, де ця ситуація руйнується - це при використанні 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

• Тримайте умовні блоки дійсно короткими.
• Викличте метод з приємним описовим іменем, якщо він виглядає так, що ваш умовний код буде більше, ніж простий рядок або два.
• Використовуйте приємні описові імена для своїх змінних.
• Переконайтесь, що умовне твердження є чітким у його значенні, а не заплутаним чи довгим. Використовуйте метод, якщо він допомагає зберегти речі чистими та читаними.

Якщо все вищезазначене не вдається, додайте дуже невеликий описовий коментар перед заявою if, щоб уточнити свої наміри. В іншому випадку насправді взагалі не повинно бути коментарів.

У C ++ або C # я зазвичай не коментую прості випадки (коли зрозуміло, що відбувається), і використовую такий стиль для коментування остаточного ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}