День 2129. #Оффтоп
Почему Разработчики Любят Чистый Код, но Ненавидят Писать Документацию? Начало
В Developer Coefficient, исследовании, заказанном финтех-гигантом Stripe, разработчики сообщили, что они тратят более 17 часов в неделю на задачи по обслуживанию, такие как отладка и рефакторинг — работа, классифицируемая ими как «мытарство».

Опрос разработчиков 2024 на StackOverflow выявил множество тех же проблем и жалоб. Наибольшим разочарованием, с большим отрывом, был технический долг. И наоборот, больше всего разработчиков радовало улучшение качества их кода и среды разработки. И заглядывая в будущее, две области, в которых разработчики чувствовали, что они получат наибольшую выгоду от инструментов GenAI, — это тестирование и документирование.

В какой степени отличная документация помогает сократить «мытарства» и технический долг, которые приводят к разочарованию и выгоранию разработчиков? И в какой степени она может поддерживать то, что делает их счастливыми, например, качество кода?

Действительно ли документация помогает?
Есть эмпирические доказательства того, что хорошая документация оказывает положительное влияние на такие работы, как рефакторинг или отладка. Мета-исследование более 60 научных работ по качеству ПО и документации показало, что преимущества отражаются во многих аспектах: сокращение продолжительности задачи, улучшение качества кода, более высокая производительность и т.п. И исследования показывают, что документация часто занимает 11% рабочего времени разработчиков.

В исследовании PLOS ONE 2023 года была разработана модель для проверки того, какие методы окажут положительное или отрицательное влияние на процесс рефакторинга. Авторы пишут, что «документация помогает в адаптации новых членов команды и обеспечивает согласованность методов рефакторинга во всей команде».

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

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

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

Ещё одна важная проблема - документация часто рассматривается как ненужные накладные расходы. Разработчики полагают, что код должен быть понятным сам по себе или что документация замедляет процесс разработки. Но это затрудняет онбординг новых членов команды и увеличивает время на задачи по обслуживанию из-за трат времени на понимание плохо документированного кода.

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

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

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

Окончание следует…

Источник: https://stackoverflow.blog/2024/11/11/developers-hate-documentation-ai-generated-toil-work/