Самодокументируемый код против Javadocs?

18

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

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

С другой стороны, у нас есть документация, такая как Javadocs. Мне это тоже нравится, но есть определенный риск, что комментарии здесь устаревают (как и комментарии в целом, конечно). Однако, если они современны, они могут быть чрезвычайно полезны, например, для понимания сложного алгоритма.

Каковы лучшие практики для этого? Где вы проводите грань между самодокументируемым кодом и javadocs?

Андреас Йоханссон
источник

Ответы:

24

Самодокументированный код (и комментарии в коде) и комментарии Javadoc имеют две очень разные целевые аудитории.

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

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

Томас Оуэнс
источник
+1, это хороший звонок. Я думаю, что мое главное преимущество в том, что я не рассматриваю это как две разные целевые аудитории, но вы правы.
Андреас Йоханссон
1
@Andiaz - я считаю полезным различать внешние границы системы (например, API службы) и классы внутри нее. Я часто работаю над проектами, где принято ставить javadoc во все публичные методы, но я гораздо больше заботлю внешние классы, чтобы дать некоторое представление о том, как должен использоваться класс (и система). Что касается внутренних классов, я предполагаю, что читатель обладает большим знанием предметной области, и минимизирую Javadoc, позволяя именам методов больше говорить самим за себя.
Стив Джексон
3
@ SteveJackson Я согласен, однако, я обнаружил, что использую больше Javadoc (даже для частных пользователей), поскольку IDE (по крайней мере, Eclipse и NetBeans) отображают комментарии Javadoc в подсказках для завершения кода. Конечно, они не так чисты, как общедоступные интерфейсы, они дают советы / заметки другим разработчикам.
Томас Оуэнс
24

Код говорит как . Комментарии говорят почему , а может даже и почему нет .

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

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


источник
2
+1: это не «или-или» в исключительном смысле. Это в инклюзивном смысле.
S.Lott
Я определенно согласен с этим. Есть ли что-то еще, что вы бы рассмотрели, когда речь заходит о Javadocs в частности? Например, я могу представить, что описание того, что делает метод, может быть полезным, например, для API.
Андреас Йоханссон
Javadocs очень легко доступны из большинства IDE. Облегчите переход к дальнейшей информации.
+1: лучшие комментарии, которые я видел, включали ссылки на статьи, в которых используемые алгоритмы были подробно обсуждены; это не то, что может быть самодокументировано в именах переменных / методов, и не обязательно должно входить в doc-комментарии, так как алгоритм является частью реализации, а не интерфейса .
Донал Феллоуз
4

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

Если, с другой стороны, у вас есть функция, в которой сначала нужно посмотреть на реализацию, чтобы понять, для чего она полезна (не делая эту информацию доступной для Javadocs), то код IMHO не самодокументируется, неважно насколько ясна реализация.

Док Браун
источник
3
+1 мой фаворит - когда стандарт кода компании требует документированных методов, но каждый использует генератор, который просто повторяет то, что код уже говорит. Утомительно и бесполезно.
Kryptic
1

Я думаю, что с javadocs все так же, как с любой документацией - главное правило:

следовать за аудиторией

Много ли людей читают ваши javadocs? Если да, имеет смысл инвестировать усилия в то, чтобы сделать это правильно.

Ваши читатели склонны пропускать чтение кода в пользу изучения javadocs? Если да, имеет смысл вдвое больше смысла тратить усилия на его написание.

  • Это как раз так в документации JDK . Полагаю, что Sun / Oracle потратили немало усилий, и они, похоже, окупаются в API-документах, часто используемых сообществом.

Теперь это твой случай? Если нет, подумайте дважды, оправданы ли усилия, вложенные в Javadocs.

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

  • Если вы слышите активные жалобы на недостаточную документацию, рассмотрите возможность инвестирования в ее улучшение.
     
    Если, с другой стороны, все, что вы слышите, это то, что разработчики жалуются на правила мозговых мертвецов, вынуждающие их тратить время на бесполезную типизацию, а значит, высоки шансы, что ваши усилия javadocs похожи на инвестиции в субстандартные ипотеки . Вместо этого подумайте о лучших инвестициях.
комар
источник
0

Я просто хочу прокомментировать обеспокоенность тем, что комментарии Javadoc могут устареть. Хотя @JonathanMerlet прав, говоря, что Javadoc должен быть стабильным, вы также можете помочь, просмотрев Javadoc и комментарии, а также код во время рецензирования. Совпадают ли комментарии с тем, что делает код? Если нет, то это неверно, и настаивайте, чтобы разработчик исправил это. Попробуйте побудить других разработчиков сделать то же самое. Это помогает обновлять не только внешнюю документацию (комментарии Javadoc), но и любые регулярные комментарии к коду. Это помогает разработчикам, которые придут после вашего рефакторинга, быстрее и проще понять код и значительно упростит его сопровождение в будущем.

Эрик Гидрик
источник
-1

Я думаю, что javadocs подходит для частей, которые должны оставаться стабильными (API), чтобы минимизировать риск устаревания комментариев, тогда как самодокументированный код отлично подходит для частых изменений (реализации). Конечно, API могут меняться в течение проекта, но иметь заголовок непосредственно перед объявлением, синхронизировать их не так уж сложно (по сравнению с комментариями на нескольких строках, объясняющими несколько строк кода)

Джонатан Мерлет
источник