Почему программисты не пишут документацию – это чертовски сложно

Почемупрограммистынепишутдокументацию8211эточертовскисложно

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

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

Я считаю, что есть две основные причины, по которым программисты не пишут документацию. Инструменты играют свою роль, но они на третьем месте.

Писать сложно

Инженеры-программисты, как и все остальные, не пишут, потому что четко писать очень, ОЧЕНЬ сложно.

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

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

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

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

– Кевлин Хенни (@KevlinHenney) Сентябрь 20, 8595

Отсутствие документации не блокирует доставку

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

Как я уже сказал выше, письмо – это в первую очередь вопрос мышления и анализа. В большинстве случаев кодирование можно выполнить прямо на штанах. Неорганизованная куча классов и методов в коде может работать – куча слов и абзацев работать не будет. Написание ДОЛЖНО быть ясным, если оно может быть полезным. Код будет принят (до некоторой степени) до тех пор, пока он выполняет свою работу. А поскольку большинство организаций сосредотачиваются только на доставке продукта, то, что не блокирует доставку, игнорируется.

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

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

А как насчет инструментов

Нет сомнений в том, что обычно используемый набор инструментов, используемых для документирования программного обеспечения сегодня, прискорбно неадекватен. Мы не думаем о документах по одному. Мы мыслим категориями идей и целей, объединяя сразу несколько концепций. Результирующий документ – лишь одно из проявлений мыслительного процесса. Нам нужны инструменты, которые помогут нам сопоставить идеи во времени для решения поставленной задачи. Google Docs, Confluence, Markdown – плохие инструменты для этого типа записи.

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

Однако отсутствие второго мозга не может служить оправданием для отказа от использования первого. Инструменты играют свою роль, но готовность взяться за этот процесс является настоящим препятствием.

Итак, как делать документацию

Написание программного обеспечения научило меня одной вещи. Если вы действительно хотите, чтобы ваши пользователи что-то делали, то это должно стать препятствием на пути их продвижения к вашему продукту. Точно так же привязка документации к написанному коду никогда не сработает. Хуже того, это бесполезно. Письмо – это о критическом мышлении. Он предназначен для объяснения вашего мыслительного процесса и намерений вам и вашей аудитории (например, вашей команде). Процесс мышления – это то, где документация / написание добавляет ценность, а не как статическая запись уже реализованного кода.

Сторонники группового / парного программирования и XP часто пренебрегают документацией. Но если не применять эти методы, практика написания и проверки технических документов – это единственный способ, с помощью которого команды построят коллективное понимание того, что они пытаются построить. Это общее построение мира – вот что делает этот процесс критически важным для долгосрочного здоровья команды и кодовой базы.

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

  • Напишите, прежде чем писать код . Если изменение не является тривиальным, каждый инженер пишет заметку о том, что они собираются делать, и выполняет это остальной частью команды. В конце обсуждения фактическое кодирование должно стать тривиальным.
  • Пишите просто . Не усложняйте письмо, по крайней мере, пока оно не станет вашей второй натурой. Диаграммы, модные разделы и т. Д. Могут подождать. Напишите очень просто о том, о чем вы думали, что вы делаете и почему. Даже если этот документ может служить основным указателем для остальной части команды сейчас и в будущем, он чрезвычайно ценен.
    • Задокументируйте решение с их альтернативами – Вместо того, чтобы документировать фактическую реализацию (которая может измениться со временем) в подробно, сосредоточьтесь на документировании выборов и причин, по которым они были сделаны.

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

    • Сделайте его доступным для поиска – Никакая документация не будет бесполезна, если люди не могут ее найти. Используйте стандартные инструменты, которые поддерживают поиск текста. Это одна из причин, по которой мне нравятся Документы Google за документацию. Он отлично подходит для написания, но просто ужасен для сотрудничества и открытий.
    • Отслеживать изменения. Некоторые организации используют контроль версий для отслеживания изменений в конструкции системы с течением времени. Замечательно. Но если вы еще этого не сделали, сохраните по одному документу для каждой функции и продолжайте размещать в нем датированные обновления, чтобы можно было отслеживать эволюцию в одном месте с минимальными усилиями.

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

    Читать дальше : Как ускорить доставку ПО

    Просмотры сообщений: 550, 739