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

Так или иначе, хороший код обычно понятен сам по себе, без добавления комментариев. Правильное (осмысленное) именование классов, полей, методов и переменных дает возможность понимать текст программы без дополнительных объяснений.

Кроме того, разбиение на методы позволяет выделять фрагменты кода, реализующие определенные функции, и имя метода само по себе является комментарием к такому фрагменту кода.

Однако вчитываться в код метода обычно труднее, чем читать описание, поэтому классы, которыми должны пользоваться другие (а лучше — вообще все классы), должны быть документированы.

Инструмент JavaDoc является неплохим средством для документирования кода на Java, позволяя , с одной стороны, создавать документацию, пригодную для использования отдельно от кода, а с другой — предоставляя все необходимые объяснения прямо в коде.

Документация (не проектная, а документация кода) должна содержать контракты всех элементов системы(классов, методов, полей), то есть описание тех условий, при которых эти элементы будут работать правильно.