💻 Документация как код

Программисты Ненавижу написание документации. В любом случае, большинство программистов. Это просто вещи, которые мешают на пути реальной работы ™, верно?

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

Даже когда программист это Непосредственно создавая код, который сам код должен найти среднюю землю между иногда-взаимно эксклюзивными целями:

• Код должен решить проблему под рукой.
• Код должен быть легко поддерживать.
• Код должен быть эффективным достаточно Отказ

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

Один из способов борьбы с этим — это так называемый «самодоступный код». Объединение тщательно продуманного переменной и функционируемых имен с методами чистого кода и отраслевыми стандартами в основном, что это о.

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

Но как вы документируете большую картину? Всеобъемлющая цель проекта? Его точка входа? Кто должен использовать это? Его зависимости? Когда это было последнее обновление? Какие стандарты кодирования он использует?

Это намного сложнее держать свой Проект Документация сухая, чем для линий кода в нем. Здесь мы попадаем в «Документацию как код» (заимствованные из концепции «инфраструктуры в качестве кода»). Цель состоит в том, чтобы каждая документация как-то связана с Функциональность самого проекта, так что если одно изменение, то оба должны измениться.

Везде, где это возможно.

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

• Глобальные конвенции. Когда я говорю «глобальный», я имею в виду по всему проектам и командам. Соблюдение Конвенции — это тип документации. Например, если все знают, что срабатываемые событиями функции всегда префиксированы с на (например ondownload () ), тогда вы можете иметь более простые названия функций без необходимости комментариев. Или если все согласны с тем, что функции обратного вызова всегда начнутся с ошибка аргумент, то код каждого может воспользоваться этим Без дополнительной документации Отказ
• Конфиги везде. Инструменты, как «Космический конфиг» Убедитесь, что облегчает одновременно следить за практикой общего отрасли, а также делать то, как вы предпочитаете их делать. Наложил информацию в Палярный , Жильчик Файлы конфигурации. Это приводит вас к инфраструктуру — как-коду и окружающую среду, а также территорию для кода, дальнейшее снижение потребностей документации.
• Автоматизировать все. Если робот что-то делает, человек не нужно ничего знать о том, как что-то работает. Если вам нужно сделать что-то регулярно в проекте, превратите эту вещь в код.
• Предотвратить настройки ошибок. Все хорошие инструменты имеют init Команда (или похожее), чтобы легко начать использовать этот инструмент с минимальной ошибкой. Лучшие интерактивно направляют пользователя через решения, которые им нужно сделать, задавая дружественные вопросы. В идеале пользователь никогда бы даже не нужно будет смотреть на полученные файлы конфигурации.
• Документы и код должны иметь те же зависимости. Это сложный, но и тот, о котором я больше всего взволнован. Это напоминает принцип инверсии зависимости. Идея такова: мы обычно рассматриваем документацию как в зависимости от кода, но что, если у нас было оба зависит от чего-то другого? Таким образом, мы могли бы внести изменения в то, что что-то — иначе, и, следовательно, код, и документы останутся в мелодии.

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

Документация API, вероятно, является лучшим примером этого, особенно для языков как гибких, как JavaScript: вы можете использовать централизованную документацию API, чтобы диктовать как функциональность вашего кода, так и документации, которая описывает ее!

Для достижения этого вы можете использовать такие инструменты, как Swagger/Openapi , жой , Экспресс валидатор , и другие.

Я только начал пытаться найти способы сделать это. Какие трюки и инструменты делают Вы использовать?

Эта статья изначально появилась в Рассылка devchat. .

Оригинал: «https://dev.to/adamcoster/documentation-as-code-40a7»