Недавно я работал над рефакторингом частей базы кода, с которыми я сейчас работаю, - не только для того, чтобы лучше понять это, но и для того, чтобы облегчить работу тех, кто работает над кодом.
Я склонен полагать, что самодокументированный код - это хорошо . Я просто думаю, что это чище, и если код говорит сам за себя, хорошо ... Это здорово .
С другой стороны, у нас есть документация, такая как Javadocs. Мне это тоже нравится, но есть определенный риск, что комментарии здесь устаревают (как и комментарии в целом, конечно). Однако, если они современны, они могут быть чрезвычайно полезны, например, для понимания сложного алгоритма.
Каковы лучшие практики для этого? Где вы проводите грань между самодокументируемым кодом и javadocs?
источник
Код говорит как . Комментарии говорят почему , а может даже и почему нет .
Ваша задача - предоставить как будущим читателям, так и разработчикам вашего кода. Положите все, что вы можете в коде, а остальное в комментариях.
Обратите внимание, что самое сложное - это принять дизайнерские решения - помните и их тоже.
источник
Использование Javadocs не имеет большого значения - поскольку сгенерированные документы содержат название ваших функций вместе с текстом из комментариев, нет абсолютно никакой причины, почему вы должны повторять что-либо в комментариях, что ясно из самого имени функции.
Если, с другой стороны, у вас есть функция, в которой сначала нужно посмотреть на реализацию, чтобы понять, для чего она полезна (не делая эту информацию доступной для Javadocs), то код IMHO не самодокументируется, неважно насколько ясна реализация.
источник
Я думаю, что с javadocs все так же, как с любой документацией - главное правило:
следовать за аудиторией
Много ли людей читают ваши javadocs? Если да, имеет смысл инвестировать усилия в то, чтобы сделать это правильно.
Ваши читатели склонны пропускать чтение кода в пользу изучения javadocs? Если да, имеет смысл вдвое больше смысла тратить усилия на его написание.
Теперь это твой случай? Если нет, подумайте дважды, оправданы ли усилия, вложенные в Javadocs.
Как уже указывалось выше, слушайте аудиторию, чтобы узнать путь.
Если, с другой стороны, все, что вы слышите, это то, что разработчики жалуются на правила мозговых мертвецов, вынуждающие их тратить время на бесполезную типизацию, а значит, высоки шансы, что ваши усилия javadocs похожи на инвестиции в субстандартные ипотеки . Вместо этого подумайте о лучших инвестициях.
источник
Я просто хочу прокомментировать обеспокоенность тем, что комментарии Javadoc могут устареть. Хотя @JonathanMerlet прав, говоря, что Javadoc должен быть стабильным, вы также можете помочь, просмотрев Javadoc и комментарии, а также код во время рецензирования. Совпадают ли комментарии с тем, что делает код? Если нет, то это неверно, и настаивайте, чтобы разработчик исправил это. Попробуйте побудить других разработчиков сделать то же самое. Это помогает обновлять не только внешнюю документацию (комментарии Javadoc), но и любые регулярные комментарии к коду. Это помогает разработчикам, которые придут после вашего рефакторинга, быстрее и проще понять код и значительно упростит его сопровождение в будущем.
источник
Я думаю, что javadocs подходит для частей, которые должны оставаться стабильными (API), чтобы минимизировать риск устаревания комментариев, тогда как самодокументированный код отлично подходит для частых изменений (реализации). Конечно, API могут меняться в течение проекта, но иметь заголовок непосредственно перед объявлением, синхронизировать их не так уж сложно (по сравнению с комментариями на нескольких строках, объясняющими несколько строк кода)
источник