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

В предисловии к книге «Структура и интерпретация компьютерных программ» сформулирован базовый ориентир для каждого инженера:

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

Дональд Кнут развивает эту идею в эссе о грамотном программировании:

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

Если проектировать программу в расчете на коллег, а не только на компилятор, потребность в комментариях резко сократится.

Комментарии как костыль

Вот фрагмент реального продакшен-кода из долгоживущей закрытой системы:

float _x = abs(x - deviceInfo->position.x) / scale;
int directionCode;
if (0 < _x & x != deviceInfo->position.x) {
    if (0 > x - deviceInfo->position.x) {
        directionCode = 0x04 /*left*/;
    } else if (0 < x - deviceInfo->position.x) {
        directionCode = 0x02 /*right*/;
    }
}

Комментарии /*left*/ и /*right*/ маскируют запутанную логику и невнятные имена. После рефакторинга код становится самодостаточным:

static const int DIRECTION_RIGHT = 0x02;
static const int DIRECTION_LEFT = 0x04;
static const int DIRECTION_NONE = 0x00;

int oldX = deviceInfo->position.x;
int directionCode = (x > oldX) ? DIRECTION_RIGHT
                  : (x < oldX) ? DIRECTION_LEFT
                  : DIRECTION_NONE;

Количество комментариев сократилось до нуля, а понятность выросла. Осмысленные константы исключили потребность в костылях.

Где комментарии действительно необходимы

Сколько бы усилий мы ни вкладывали в рефакторинг, сам по себе код не способен передать весь контекст принятия решений. Как отмечал создатель проекта Macintosh Джеф Раскин:

Код не может объяснить, почему написана программа и почему выбран именно этот подход среди десятка альтернатив.

Пример уместного комментария, фиксирующего инженерное решение:

/* Бинарный поиск оказался медленнее алгоритма Бойера-Мура на наших объемах данных.
   Используем поиск по подстроке, несмотря на нетипичность задачи. */

То, что очевидно автору в момент написания, через полгода поставит в тупик всю команду.

Код отвечает на вопрос «как» работает система. Комментарии фиксируют ответ на вопрос «почему» она устроена именно так. Сохраняйте этот баланс в повседневной работе.