День девятьсот пятый. #BestPractices
Лучшие Практики Написания Комментариев к Коду. Продолжение
Начало

3. Если вы не можете написать чёткий комментарий, возможно, проблема в коде
Самый печально известный комментарий в исходном коде Unix: «Никто не ожидает, что вы это поймёте», - располагался перед каким-то непонятным кодом переключения контекста. Позже Деннис Ричи объяснил, что это было написано в смысле "Этого не будет на экзамене", а не чтобы потроллить читателей. К сожалению, выяснилось, что ни он, ни соавтор Кен Томпсон сами не понимали этого кода и позже пришлось его переписать.

Это напоминает закон Кернигана: «Отладка в два раза сложнее, чем изначальное написание кода. Следовательно, если вы напишете код настолько умно, насколько это возможно, вы по определению недостаточно умны, чтобы отлаживать его.»

Предупреждать читателей, что они могут не понять ваш код, всё равно что включить аварийку в машине: признаться, что вы знаете, что нарушаете ПДД. Вместо этого перепишите код так, чтобы вы понимали его достаточно хорошо, чтобы объяснить кому-то, или, ещё лучше, чтобы объяснения не требовалось.

4. Комментарии должны прояснять ситуацию, а не запутывать
Обсуждение плохих комментариев было бы неполным без этой истории из книги Стивена Леви «Хакеры: герои компьютерной революции»:
[Питер Сэмсон] отличался тем, что отказывался добавлять поясняющие комментарии к своему исходному коду. Одна хорошо распространённая программа, написанная Сэмсоном, содержала сотни инструкций на языке ассемблера, с одним комментарием рядом с инструкцией, содержащей число 1750. Комментарий был: «RIPJSB», - и люди ломали голову над его значением, пока кто-то не понял, что 1750 - это был год смерти Баха, и что Сэмсон написал аббревиатуру для «Покойся с миром Иоганн Себастьяна Баха».

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

5. Поясняйте нестандартный код в комментариях
Рекомендуется комментировать код, который кто-то может счесть ненужным или избыточным, например этот код из App Inventor:

final Object value = (new JSONTokener(jsonString)).nextValue();
// Note that JSONTokener.nextValue() may return
// a value equals() to null.
if (value == null || value.equals(null)) {
    return null;
}

Без этого комментария кто-то может «упростить» код или рассматривать его как загадочное, но важное заклинание. Сэкономьте время и беспокойство будущих читателей, написав, зачем нужен код.

Необходимо принять решение относительно того, требует ли код пояснения. Например, в учебнике по Kotlin есть такой код:

if (b == true)

Странно, почему бы не использовать просто

if (b)

, как это было бы в Java или C# (да и куче других языков). Однако, оказывается, что обнуляемые булевы переменные в Kotlin специально явно сравниваются с true, чтобы избежать уродливой проверки на null:

if (b != null && b)

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

Продолжение следует…

Источник: https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/