Виды комментариев

У Java программ могут быть два вида комментариев: комментарии реализации и документирующие комментарии. Комментарии реализации, аналогичные комментариям в C++, ограничиваются /.../ и //. Документирующие комментарии (известные как “doc comments”) встречаются только в Java и ограничиваются / *.../. На основе документирующих комментариев с помощью утилиты javadoc могут быть созданы файлы документации в формате HTML.

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

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

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

Замечание: Частота комментариев иногда отражает низкое качество кода. Если Вы почувствуете, что нужно добавить ещё комментариев, подумайте, вероятно нужно переписать такой код, чтобы сделать его более понятным.

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

Комментарии никогда не должны включать служебные символы, такие как возврат каретки и backspace.

Типы комментариев реализации

Программа может содержать такие стили комментариев реализации, как: "блочный", "однострочный" или "комментарий в конце строки"