[JavaDoc] его написание ???

rid2000

Привет всем!
Меня попросили выступить с докладом на эту тему.
ИМХО (и эторазделяют многие) результатами разработки ПО должны быть (Код + доК)...
Но....
При попытки написания javaDocs для своего ПО у меня возникли большие трудности...
В смсле:
- что писать?
- если написал, то пару слов
- если пару слов, то все они отличаются на одно слово
А может я классы и его методы не логично сформировал... Да вроди все удобно... для меня...
Есть ли технологии по написанию кода и дока?
Есть ли какие-нибудь правила или фишки по данной теме...
Так как я имею образование МГУ, то не должен упасть в грязь лицом...
Выслушаю Вас... с большим удовольствием

enochka1145

Ничего не понял - и наверно я такой не один. Уточни, если хочешь помощи, тебе нужно сам javadoc написать или показать, что это и как им пользоваться?
В общем, как в хорошем деловом письме, чётко укажи, что конкретно ты хочешь от читателя, а не заставляй его теряться в догадках.

sergei1969

он спрашивает, что именно ему описывать в комментариях к классам/методам, а то слишком мало получается в итоге
2: почитай API Docs и посмотри, о чём там обычно пишут

rid2000

Лана... забейте...
Смотрел я их...
А думал может... типа метода по написанию есть...

puare

Рекомендую к прочтению руководство от Sun
Должно помочь

enochka1145

Спасибо!

puare

Спасибо!

Сопсно незачто, просто погуглил чуток. Там еще в Code Convention про JavaDoc немного сказано, я ссылку не стал постить, сами найдете.
Happy java!

durka82

Попробуй связывать код с требованиями к проекту.

puare

А это как? Разве то, что код реализует требования проекта не является связью?

durka82

код реализует требования проекта

Разве из кода это видно?

А это как?

Например, давать ссылки на репозиторий требований.
Если среда разработки требования поддерживает - должно получиться еще проще.

puare

Например, давать ссылки на репозиторий требований

не стоит, имхо, потому как то, что метод делает должно быть ясно из его названия (одно из требований code convention а алгоритмы в требованиях не всегда описывают. JavaDoc же нужет для описания входных параметров, выхода и выбрасываемых исключений. Кроме того, если метод имеет нетривиальный алгоритм работы, ПОСЛЕ его объявления, но ПЕРЕД телом в ОБЫЧНОМ комментарии подробно описывается все нетривиальное, и это АФАИК, тож включается в JavaDoc при генерации.

durka82

что метод делает должно быть ясно из его названия

А класс?

одно из требований code convention

А это разве не рекомендация?
Ведь далеко не всегда так можно сделать.

алгоритмы в требованиях не всегда описывают

Их там чаще не описывают, чем описывают.

JavaDoc же нужет для описания входных параметров, выхода и выбрасываемых исключений. Кроме того, если метод имеет нетривиальный алгоритм работы, ПОСЛЕ его объявления, но ПЕРЕД телом в ОБЫЧНОМ комментарии подробно описывается все нетривиальное, и это АФАИК, тож включается в JavaDoc при генерации.

А то, что собственно делает этот код, должно же быть как-то описано.
А указывая, что код реализует такое-то требование, мы сообщаем, зачем он собственно нужен.