Почему важно давать хорошие имена в коде?

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

Что решает хорошее имя:

Намерение: expireSession() говорит больше, чем process().
Контекст: calculatePriceWithTax() понятнее, чем просто calculate().
Контракт: isEmpty() (логический результат) и getSize() (число) — разное поведение, и имя это чётко показывает.

Простые, но работающие правила:

Глагол + объект для действий: sendInvoiceEmail().
Ясное существительное для данных: PaymentRequest, CustomerId.
Без тайнописи вроде cfg, mgr, tmp2.
Если логика нетривиальна, пусть имя объясняет “почему”: retryOnRateLimit().

А комментарии не нужны? 🤔

Нужны, но точечно. Пиши их там, где код сам не может выразить мысль:

когда решение неочевидное;
когда нужна историческая справка или ссылка на ADR.

Главное не использовать комментарии, чтобы объяснять то, что код и так должен рассказывать сам.

👉 Java Portal