Оба проекта через свои README-файлы, журналы изменений, комментарии в коде рассказывают о себе так, чтобы новичок смог понять, где что находится, как и почему что-то делается. Это отличные примеры для разработчиков, желающих улучшить документирование своего кода и архитектуры ПО.
Хорошая документация необходима при написании ПО, особенно если другие люди будут просматривать кодовую базу, вносить в нее свой вклад или если вы сами планируете вернуться к ней позже. Пользователи выиграют от наличия инструкций по использованию и объяснений, когда ПО следует и не следует применять.
Преимущества хорошей документации многочисленны:
- Экономия времени, особенно при работе в команде. Вместо часового объяснения кодовой базы каждому новому участнику проекта, они могут заранее ознакомиться с документацией, что приведет к более продуктивному обсуждению.
- Ваш проект с открытым исходным кодом с большей вероятностью получит поддержку со стороны и будет существовать после того, как вы не сможете его поддерживать.
- Больше людей могут использовать ваше приложение или библиотеку, потому что меньшему количеству людей придется разбираться во всем самостоятельно.
- Документация помогает структурировать мышление и выявлять недостатки, так как вы записываете свои мысли, что высвечивает потенциальные проблемы, которые в противном случае остались бы незамеченными.
Теперь давайте рассмотрим и изучим два проекта с открытым исходным кодом, которые имеют отличную документацию.
esbuild
esbuild – бесплатный сборщик и минификатор модулей с открытым исходным кодом для JavaScript.
![esbuild](https://media.proglib.io/posts/2024/03/26/96a9011048c7fedcf9c3045a8bab0051.png)
README esbuild фокусируется исключительно на конечном пользователе инструмента. Сначала даются ссылки на основные разделы документации, такие как «Начало работы». Раздел «Почему?» кратко и с визуализацией объясняет, почему кто-то выберет эту библиотеку, а не другие решения. Перечислены возможности инструмента, что помогает определить, отвечает ли он потребностям пользователя. Также можно изучить FAQ, страницу «Начало работы», документацию по API и документацию по конкретной функции.
Архитектура документации esbuild
В каталоге docs находятся два файла: architecture.md и development.md. Документ начинается с оглавления и введения, объясняющего цель документа.
![Архитектура документации esbuild](https://media.proglib.io/posts/2024/03/26/d1c2f6d8c6f51e190c5af75b75e52fd2.png)
После краткого введения обсуждаются принципы проектирования: для всего, что явно не объяснено в последующих частях, можно предположить, что они являются результатом этих принципов.
![Принципы проектирования esbuild](https://media.proglib.io/posts/2024/03/26/f12df40663b62ec61eaf16d27f0f9612.png)
Документ содержит множество схем для объяснения концепций. Ниже мы видим схему, показывающую различные фазы того, как работает esbuild, включая указание на то, какие шаги выполняются параллельно.
Иллюстрации с узлами и ветвями полезны, если объясняемый процесс включает шаги, которые возвращаются друг к другу, что трудно передать только текстовым описанием.
![Иллюстрация с узлами и ветвями](https://media.proglib.io/posts/2024/03/26/d395b8cd014dd6f39b99e2990d96d04f.png)
Остальная часть документации по архитектуре esbuild схожа. Она многое объясняет в тексте, но также предоставляет графику для визуализации сложных концепций. Фрагменты кода, таблицы и форматирование помогают понять, как и почему все работает именно так.
![Фрагменты кода, таблицы и форматирование помогают понять, как и почему все работает именно так](https://media.proglib.io/posts/2024/03/26/4e240d91b92b58eceda8b0c190aeb53b.png)
Журнал изменений esbuild
Подробная документация esbuild распространяется и на журнал изменений. Каждая запись содержит краткое описание, подробное объяснение и пример кода, показывающий вывод до и после изменения.
![Журнал изменений esbuild](https://media.proglib.io/posts/2024/03/26/32e6cdc042cfceca4a0936493a3f718f.png)
Качественная документация сыграла важную роль в росте популярности esbuild. На момент написания у проекта 37 000 звезд на GitHub, и он используется в 4.6 миллионах проектов.
![✍️ Как написать отличную документацию: 2 впечатляющих примера с открытым исходным кодом](https://media.proglib.io/posts/2024/03/26/e808354af3080fb5eda1ed0720d8d9ff.png)
Стань супермегаопытным программистом на курсах Proglib Academy со скидкой 35% до 1-го апреля!
- Математика для Data Science
- Базовые модели ML и приложения
- Алгоритмы и структуры данных
- Основы программирования на Python
- Основы IT для непрограммистов
- Frontend Basic: принцип работы современного веба
Redis
Redis – резидентная система управления базами данных класса NoSQL с открытым исходным кодом.
Введение и архитектура README-файла Redis
Раздел, представляющий Redis, краток, а остальная часть README предназначена для людей, вносящих вклад в кодовую базу Redis или читающих ее. Этот README ориентирован как на конечных пользователей, так и на контрибьюторов. Документация для обеих групп доступна, хотя и находится в разных местах.
В разделе для контрибьюторов README рассказывает о компиляции исходного кода Redis, решении распространенных проблем сборки, нюансах с конкретными операционными системами, запуске и установке Redis. Он охватывает основы и освещает типичные проблемы, позволяя начать работу и избежать трудностей в дальнейшем.
Однако особенно выделяется раздел о внутреннем устройстве Redis. Он начинается с описания структуры исходного кода, позволяя новичку понять, где искать нужное и в каких директориях он будет работать чаще всего.
![Описание структуры исходного кода Redis](https://media.proglib.io/posts/2024/03/26/702ad052465c9b346c4593ea7a4a60b3.png)
Затем рассматриваются ключевые файлы и их структура.
![Ключевые файлы Redis](https://media.proglib.io/posts/2024/03/26/a14757b1f05316cdb22ce6ee9174ff3d.png)
Комментарии
Любая хорошо документированная кодовая база обычно имеет качественную документацию в виде комментариев к коду. В исходном коде Redis мы видим примеры, где несколько абзацев объясняют одну строку кода.
![Комментарии в документации Redis](https://media.proglib.io/posts/2024/03/26/408f7d56356fc2762cd67f28b5c74111.png)
Важно подчеркнуть, что длинные объяснения тривиальных строк кода не обязательны. Если операция проста и не требует дополнительного контекста для понимания, почему она написана именно так – лучше обойтись без комментария. Комментарий, который говорит то же самое, что и строка кода, излишен, если только строка кода не особенно сложна для чтения (в этом случае ее, вероятно, следует переписать) или цель не состоит в обучении.
Подведение итогов
- Тщательная документация экономит время не только для вас, но и для других.
- Некоторые проекты предназначены исключительно для развлечения или чего-то, над чем вы работаете в одиночку, и вы не уверены, вырастет ли проект в будущем. В таких ситуациях можно ничего не документировать.
Комментарии