Комментируем всё. Исключение - @Override
методы, т.к. комментарий должен быть в базовом классе.
Соглашение к подходу комментирования методов:
- Первое предложение описывает суть метода и является отдельным абзацем.
- Первое предложение начинается с глагола.
- Остальное описание в отдельном(ых) абзацах.
- Для перечисления стоит использовать
<ul><li>...</li></ul>
. - HTML-теги используются только в Java.
Общие правила:
- В конце всех предложений ставится точка.
- Для подсказок об опечатках рекомендуется установить плагин для IDEA Grazie или подобное.
Рекомендации:
- Стоит переиспользовать одни и те же фразы, чтобы описать одну и ту же сущность. Например, комментарии конструкторов - это комментарий класса, к которому добавлено слово "Конструктор". Это позволяет:
- Иметь единый стиль
- Не тратить силы на продумывание каждый раз нового описания