Изучение выигрышей / потерь производительности документации кода

После долгих поисков я не смог ответить на основной вопрос, касающийся предполагаемого известного в мире разработки программного обеспечения:

ЧТО ИЗВЕСТНО:

Применение строгой политики в отношении надлежащей документации по коду (будь то теги Doxygen, Javadoc или просто обилие комментариев) увеличивает затраты времени на разработку кода.

НО:

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

ВОПРОС:

Требуется ли дополнительное время разработки, чтобы гарантировать, что такая документация компенсируется повышением производительности в будущем (в строго экономическом смысле)?

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

Заранее спасибо!

Статья «Типографский стиль - это больше, чем косметика» довольно старая, но очень интересная: http://portal.acm.org/citation.cfm?id=78611 .

Будучи старым, он не включает в себя все модные вещи, которые были бы возможны в наши дни, но он ясно показывает, что документация кода имеет значение.

Для тех, кто, как и я, не имеет доступа к цифровой библиотеке ACM, они создали две группы программистов и дали им один и тот же код для изучения. Группа A получила только код с обычными комментариями, группа B получила довольно распечатанный список с оглавлением, перекрестными ссылками и всеми тонкостями, которые были возможны еще в 1990 году.

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

Чтобы сбалансировать группу, у них было одинаковое количество опытных и младших программистов.

Что ж, оказалось, что группа B (та, что с довольно распечатанным списком) в большинстве тестов показала лучшие результаты, чем группа A. И в отдельных случаях только самые опытные из группы А смогли превзойти младшего программиста из группы В.

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

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

Я не могу подтвердить это никакими вескими доказательствами, кроме здравого смысла.

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

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

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

На любом API, который немного нетривиален, документирование API в коде практически бесполезно. Это связано с тем, что сила API заключается в том, как он работает вместе как единое целое (а не в том, как работают отдельные методы / объекты).

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

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

Любые методики наилучшего предположения, такие как «все общедоступные методы» или все классы в данном пакете и т. Д., Могут помочь, но слишком грубы, чтобы рекомендовать их за пределами конкретных случаев использования.

Мое предложение: научите ваших разработчиков хорошей практике, как определять методы, которые важны для документирования (формальный или неформальный API, обычно используемые, методы-заглушки, сложные или эзотерические), и позволяйте им управлять собой.

(Близко связано: может ли быть слишком много единообразия в стандартах кодирования? )

^{Извинения, которые я не могу процитировать, но я подозреваю, что это проблема, когда любые попытки измерить ее слишком сильно повлияют на результат, чтобы сделать общие выводы.}

Я думаю , нам нужно отделить «регулярный» код из общедоступного API , в этом отношении. Для обычного кода я пришел к полному согласию с большинством других ответчиков в этом коде, который должен самодокументироваться и читать почти как прозу . Если мой код не такой, обычно это моя вина, поэтому вместо того, чтобы документировать, он должен быть реорганизован. Небольшие методы, которые делают только одну вещь за раз, работая на одном уровне абстракции, имея правильное и описательное имя , могут помочь в этом.

Проблема с комментариями в том, что они гниют. Как только вы добавляете комментарий, он начинает жить независимо от кода, который он сопровождает. Насколько велика вероятность того, что следующий разработчик, который модифицирует код, также покорно обновит соответствующий комментарий? По моему опыту, близко к нулю. Конечный результат после нескольких модификаций состоит в том, что комментарий озадачивает или вводит в заблуждение людей, а не помогает им.

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

Плодотворную работу по этой теме Чистый код .

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

Вопрос в том, сэкономите ли вы время, документируя свой код, по сравнению с каждым последующим разработчиком, который пытается выяснить, что делает. Если ваш код просматривает код без каких-либо вопросов о том, что он делает, вы, вероятно, в хорошей форме. Нетрудно описать предположения, которые вы делаете относительно входных данных. Допустим, ваш метод берет целочисленный объект и возвращает строковый объект. Может ли int быть нулевым? Есть ли минимальное / максимальное значение (кроме integer.MinValue / MaxValue)? Может ли он вернуть пустую строку или ноль? Это бросает какие-либо исключения? Конечно, любой может найти их осмотром, но если достаточное количество других разработчиков будут использовать ваш код, экономия каждые несколько минут стоит вашего времени. Кроме того, это дает тестерам возможность создавать тесты для подтверждения вашего кода.

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

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

В своей карьере я видел код с различными уровнями документации и качества (обратите внимание, что документация и качество являются ортогональными проблемами). Я бы предпочел, чтобы время, потраченное на документацию, использовалось для улучшения качества. Для простого случая есть такие инструменты, как GhostDoc, которые могут посмотреть на функцию и сгенерировать комментарии для вас. Если GhostDoc может генерировать содержательный комментарий, в котором говорится о том, что делает ваша функция, то вы, очевидно, достигли цели, имея хорошо названные функции.

Во многих случаях GhostDoc даже не может рассказать вам, что на самом деле делает функция. Ваше время лучше потратить на решение этой проблемы и (возможно) использование ghostdoc для автоматической генерации вашего кода.

См. Чистый код и PPP от Боба Мартина для более глубокого обсуждения.