Основная документация, необходимая программному проекту

Основная документация, необходимая для разработки программного обеспечения

Поднимите свою команду на новый уровень

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

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

Диаграмма базы данных

Абсолютный минимум документации в программном проекте, взаимодействующем с базой данных (особенно реляционной), — это диаграмма базы данных.

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

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

Соглашения об именах

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

Отличным примером соглашения об именах является тип регистра, который вы хотите использовать в своих проектах, например, camelCase, PascalCase или змея_case. Конечно, они могут различаться в зависимости от контекста. Возможно, все методы внутри класса написаны на PascalCase, но их параметры написаны на camelCase.

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

Определение готовности

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

Примером определения «Готово» может быть:
– Выберите функцию и измените ее состояние на «Выполняется»
– Реализуйте все, что определено в описании функции
– Создайте модульные тесты для всех возможные потоки вашей функции
– Создайте запрос на слияние
– После того, как хотя бы один рецензент примет PR, объедините его с основной веткой
– Измените состояние функции на «Готово к Тестирование»
— команда контроля качества тестирует функцию и, если дефектов не обнаружено, меняет статус на «Готово».

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

Вики-страницы

Последний пункт, который я хотел бы затронуть в этой статье, — вики-страницы. Они относятся к информации, записанной вне самого проекта, например, в Azure Wiki или Atlassian Confluence.

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

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

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

Как всегда, если вам понравилась статья, обязательно подпишитесь на меня на Medium, чтобы получать уведомления, когда я публикую другие статьи, подобные этой. Увидимся! 👋