Неправильно ли не создавать Javadoc для моего кода?

Я делаю много Java-программирования на своей работе (я стажер), и мне было интересно, является ли правило создания javadoc для сопровождения моего кода. Я обычно документирую каждый метод и класс в любом случае, но мне трудно придерживаться синтаксиса Javadoc (записывая переменные и вывод, чтобы синтаксический анализатор мог генерировать html).

Я просмотрел много программирования на C и даже C ++, и мне нравится, как они комментируются. Неправильно ли не поставлять javadoc с моим кодом?

6 голосов | спросил n0pe 21 J0000006Europe/Moscow 2011, 22:01:33

7 ответов


21

В любом письме вы пишете для своей аудитории. Ваша аудитория - разработчик обслуживания, который может быть после вас через 3 года после того, как вы забыли детали того, как все это работает.

Одиночный код выброса, возможно, можно прокомментировать. API, которые должны потреблять другие разработчики, необходимо документировать больше.

Никому не нужен javadoc, который только повторяет подпись метода (например, «Это метод с возвращаемым значением void и именем HelloWorld и вызывается без параметров»)

ответил MatthewMartin 21 J0000006Europe/Moscow 2011, 22:09:03
7

Это, как правило, решение команды /компании; нет правильного или неправильного ответа.

Он также применим к типу разрабатываемого программного обеспечения; извне подвергается воздействию и потребляется в сравнении с внутренним воздействием и потреблением.

С любыми комментариями; сделайте их полезными. Не прерывайте подпись метода.

ответил Aaron McIver 21 J0000006Europe/Moscow 2011, 22:03:51
5

Javadoc в значительной степени является общепринятым стандартом для документирования Java-кода. Возможность конвертировать его в HTML - это лишь одно из преимуществ; гораздо важнее то, что все основные Java IDE понимают это также, и они будут использовать его для отображения контекстно-зависимой справки во время вашего кода. Если вы не придерживаетесь синтаксиса javadoc, это не работает и делает работу с вашим кодом очень раздражающей для людей, которые привыкли к этой удобной функции (и особенно в мире Java, кодирование в среде IDE, а не простой текстовый редактор является нормой).

Короче говоря, использование собственного стиля комментариев - эгоистичный, упрямый и ребяческий. Изучите javadoc. Это не так сложно, и это может быть даже полезно для вашей будущей карьеры.

ответил tdammers 21 J0000006Europe/Moscow 2011, 22:49:54
5
  

Неправильно ли вы не поставлять javadoc с моим кодом?

Да. Неправильно создавать значимые javadoc.

Неправильно писать бессмысленный, неинформирующий шаблон javadoc.

ответил S.Lott 21 J0000006Europe/Moscow 2011, 22:09:16
2

Я бы сказал, что неправильно ошибаться, чтобы убедиться, что разработанный вами код четко и понятно документирован для ситуации. То, что это означает, является ситуативным.

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

Что касается javadoc в частности, это зависит от вас и вашего работодателя, но вы обязательно должны быть уверены, что что-то останется для другого человека, который будет использоваться.

ответил asfallows 21 J0000006Europe/Moscow 2011, 22:08:33
2

Если проблема в том, что вам трудно придерживаться синтаксиса javadoc, хорошая IDE поможет. Например, в Eclipse откройте комментарий с /** введите @, и функция завершения кода отобразит доступные аннотации.

Проверка результата так же просто, как наведение указателя мыши на имя метода. Это также позволяет быстро и легко искать документацию без перекодировки в веб-браузер для просмотра репозитория документации.

ответил Foozilla 22 J000000Friday11 2011, 09:00:27
0

JavaDoc упрощает использование кода. Я сомневаюсь, что это помогает лучше, чем обычные комментарии, когда дело доходит до исправления или изменения кода, но использование ваших классов в других проектах намного проще и, следовательно, более вероятно, когда комментарии JavaDoc позволяют другим программистам находить и использовать ваши классы и методы. Поскольку повторное использование кода обычно лучше, чем изобретать колесо, отсутствие JavaDoc вряд ли приемлемо, если только ваш код не настолько плох, что повторное использование в любом случае не является вариантом.

ответил user281377 22 J0000006Europe/Moscow 2011, 00:10:15

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132