Нужны ли комментарии

Комментарии нужны, но не везде

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

Что НЕ комментировать

// ❌ Бесполезные комментарии
private int age; // переменная возраста
public void increaseAge() {
    age++; // увеличиваем возраст на 1
}

Этот код и так очевиден. Комментарии просто загромождают код.

Что комментировать

1. Сложную бизнес-логику:

// Используем exponential backoff для повторных попыток:
// 1-я попытка: 1сек, 2-я: 2сек, 3-я: 4сек
// Это снижает нагрузку на API при сбое
private long calculateBackoffDelay(int attempt) {
    return 1000L * (1L << Math.min(attempt, 10));
}

2. Нестандартные решения:

// Возвращаем null вместо Optional, т.к. метод используется в 50+ местах
// Рефакторинг отложен на следующий спринт
public User findByEmail(String email) {
    return userRepository.findByEmail(email).orElse(null);
}

3. Важные warnings:

// ВНИМАНИЕ: этот метод не потокобезопасен!
// Используй synchronized или вызывай из одного потока
public void updateCache(String key, Object value) {
    cache.put(key, value);
}

4. Why, а не What:

// ❌ Неправильно (комментирует то, что видно из кода)
// Создаём список
List<String> names = new ArrayList<>();

// ✅ Правильно (объясняет почему)
// Используем ArrayList вместо LinkedList, т.к. нужен быстрый доступ по индексу
List<String> names = new ArrayList<>();

JavaDoc для публичного API

/**
 * Вычисляет процентный прирост между двумя значениями.
 * 
 * @param initial начальное значение
 * @param final финальное значение
 * @return процент прироста (может быть отрицательным)
 * @throws IllegalArgumentException если initial < 0 или final < 0
 */
public double calculateGrowth(double initial, double final) {
    if (initial < 0 || final < 0) {
        throw new IllegalArgumentException("Values must be positive");
    }
    return ((final - initial) / initial) * 100;
}

Антипаттерны

• Устаревшие комментарии — хуже чем никакие, они дезориентируют
• Комментарии вместо коммитов — используй git history, не комментарии
• Комментарии вместо рефакторинга — если код сложный, переписать, не комментировать

Правило золотого баланса

Хороший код = 5-10% комментариев. Если их больше — рефакторь код, выноси логику в методы с понятными названиями:

// ✅ Вместо комментариев — понятные имена методов
if (isValidOrder(order) && hasEnoughStock(order) && processPayment(order)) {
    shipOrder(order);
}

Вывод: Пиши комментарии только для сложной логики, нестандартных решений и API документации. Остальное должно быть понятно из названия переменных и методов.