Какой метод комментирования наиболее распространен или действительно имеет значение?
Я использовал
/**
* (Method description)
* @param
* @return
* etc
*/
Однако я прочитал:
Precondition:
Postcondition:
Есть ли более "профессиональный" способ комментирования?
Ниже приведены соглашения о кодировании Java для комментариев, рекомендованных Oracle:
Вот рекомендации Google для платформы Android:
Более подробную информацию о стилях и соглашениях для Javadoc см. здесь:
Прежде всего, у всех, у которых есть читаемый код и читаемые комментарии, есть две вещи, которые совершенно разные.
Считываемый код - это код, который использует хорошую переменную, метод, имена классов и т.д.
Читаемые комментарии - скорее вопрос личного вкуса. Некоторым людям нравятся комментарии, чтобы следовать грамматическим правилам, которые будут использоваться для написания книги, в то время как другие не заботятся о грамматическом материале. Вы можете перейти по этой ссылке:
http://www.oracle.com/technetwork/java/codeconventions-141999.html#385
Из прочитанного кода и комментариев вы можете создать документацию с помощью doxygen.
Стиль комментария в первом примере - это не просто соглашение, оно является стандартом для инструмента документации, называемого Javadoc. Если вы будете следовать этому стилю комментариев Javadoc, вы сможете легко генерировать html-форматированную документацию для всего исходного кода.
Я бы просто выполнил стандарт, определенный Sun (Oracle) для написания Javadoc. Javadoc направляется всеми разработчиками единогласно:). Для получения дополнительной информации нажмите здесь
Я также прошу вас сделать следующий поиск в Stackoverflow для большого количества вопросов и комментариев при комментировании.
Эта ссылка очень полезна, и я давно ее использую и очень помог мне. Это создает очень хороший и документированный код с максимальной удобочитаемостью.