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

Классический пример ритуального комментирования:

'*************************************************
' Функция: CopyString
'
' Назначение: Копирует строку из исходного источника (source) в целевой (target).
'
' Алгоритм: Получает длину source, посимвольно копирует каждый символ в target,
' инкрементируя индекс массива.
'
' Входные данные: source — исходная строка
' Выходные данные: target — скопированная строка
'
' Автор: Дуайт К. Кодер
' Дата: 01.10.2004
' Телефон: (555) 222-2255
' Любимый автомобиль: Pontiac Aztek
'*************************************************

Такие «простыни» не несут практической ценности: они повторяют очевидное и устаревают при первом же изменении сигнатуры.

Три уровня выразительности

Взгляните на код без комментариев:

r = n / 2;
while (abs(r - (n / r)) > t) {
    r = 0.5 * (r + (n / r));
}
System.out.println("r = " + r);

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

Попытка решить проблему комментарием:

// Вычисление квадратного корня методом Ньютона — Рафсона
r = n / 2;
while (abs(r - (n / r)) > t) {
    r = 0.5 * (r + (n / r));
}
System.out.println("r = " + r);

Теперь смысл ясен, однако сам код остался невнятным. Правильное инженерное решение — вынести логику в отдельный метод с говорящим именем:

private double approximateSquareRoot(double number, double tolerance) {
    double root = number / 2;
    while (Math.abs(root - (number / root)) > tolerance) {
        root = 0.5 * (root + (number / root));
    }
    return root;
}

System.out.println("r = " + approximateSquareRoot(number, tolerance));

Код стал понятным без единой строчки пояснений. Выделение метода и осмысленные имена переменных решили проблему читаемости на фундаментальном уровне.

Пишите код так, будто комментариев не существует

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

Текст на естественном языке требует писательского мастерства. Нечетко сформулированный комментарий запутывает читателя сильнее, чем его отсутствие.

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