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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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