Говорящие имена методов и самодокументирующийся код в Java

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

Чтобы в нем было легко разобраться даже если пройдет много времени.

Как пользовались методами/функциями лет двадцать назад? Выносили в них повторяющийся код. А так просто оставляли комментарии в программе.

Но если вы перед каким-то блоком кода оставляете комментарий, как этот блок работает – лучше всего вынести этот блок в отдельный метод и дать методу название, исходя из вашего комментария.
Тогда пропадет необходимость в лишнем комментарии (а главное, частая проблема: рассинхронизация кода и комментариев) и по названию метода будет сразу понятно, что он делает.

В любом случае старайтесь следовать принципу, чтобы метод (функция) выполнял только какую-то одну задачу и то, что он делает, было отражено в его названии.

Типичные ошибки:
Например, если метод что-то возвращает, не называйте его setSomething(), ведь set переводится как "установить". Называйте его, не используя никаких приставок или используя приставку get (получить).

Пример ошибки:

//   public int setCounter() { // название не соответствует коду
   public int getNextCount() { // лучше так или incrementCounter()
        counter++;
        return counter;
    }

Не поручайте методу слишком много работы, ведь тогда пропадает смысл разбиения кода на отдельные методы, это все равно, что написать весь код в одном методе на десятки тысяч строк. Когда-то давно это было ок, но сейчас разбираться в "каше" будет слишком дорого и долго.

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

ОК! ИДЕМ ДАЛЬШЕ!