Как начать программный проект с качественным мышлением

Построение качественного программного обеспечения не является легкой задачей и требует много практики и опыта.

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

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

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

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

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

Качество — это не то, что вы можете легко добавить позже.

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

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

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

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

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

Примечание : Во время этой статьи я ссылаюсь на некоторые инструменты, которые мне нравятся, и которые вы можете использовать для различных вариантов использования в жизненном цикле разработки. Эти инструменты являются просто предложениями. В центре внимания этой статьи — не инструмент, а процессы и практики. Используйте любой инструмент, который вам нравится или знакомы с ним.

Определите процесс разработки, инструменты и т. Д.

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

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

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

Создайте основы для хорошей документации

Документация очень важна, но часто рассматривается как небольшая задача в разработке программного обеспечения. Это еще более важно, если вы работаете в команде, проекте с открытым исходным кодом или если вы создаете что -то, что будет использоваться третьими лицами Пример: общественность, лицом к лицу API.

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

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

Вы также можете написать какое -то «руководство по продукту» для ваших конечных пользователей.

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

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

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

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

Если вы строите API, посмотрите на Спецификация OpenAPI Анкет

Я предпочитаю использовать открытые стандарты, так как они облегчают интеграцию с другими инструментами для создания мощных рабочих процессов и избегания блокировки, так что Markdown и Open API, безусловно, являются отличным выбором.

Определить и обеспечить соблюдение стандартов и руководящих принципов кодирования

Это особенно важно при работе в команде и поможет вашему коду быть последовательным и легким для чтения.

Кто не просмотрел PR, это была очень маленькая функция, и в итоге получил множество измененных файлов, потому что разработчик настроен на использование 2 пространств, где оригинальный разработчик использовал 4 пространства? Это добавит много накладных расходов в процесс проверки кода и бесполезные изменения в кодовой базе.

Вам не нужно изобрести колесо. Большинство языков программирования имеют какие -то рекомендуемые руководящие принципы стиля. PHP имеет PSR-2 , JavaScript есть Airbnb или Стандартный , Python есть PEP8 Анкет

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

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

Eslint для JavaScript или Php_codesniffer Для PHP может использоваться для обнаружения нарушений стандартов кода. Некоторые инструменты, такие как Красиво , GOFMT или PHP-CS-Fixer может даже отформатировать ваш код и исправить проблемы стиля автоматически, в соответствии с определенными стандартами.

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

Хороший способ обеспечить, чтобы любой коммит, выполненный в репозитории git Hooks запустить эти инструменты на каждом коммите или толчок. Я недавно нашел Предварительный Коммит который помогает настройке Git Hooks в вашем проекте. Вы можете попробовать.

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

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

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

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

Чтобы облегчить создание нового проекта со всеми этими уже настроенными инструментами и готовыми к началу разработки, вы можете создать некоторые базовые шаблоны проекта, которые разработчик может клонировать. GitHub только что представил Шаблоны репозитория И вы также можете использовать такие инструменты, как SAO или Йомен для этой цели.

Настройка инструментов статического анализа для выявления кода рано

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

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

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

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

Если вы хотите пойти дальше и иметь более подробный взгляд и показатели качества кода проекта, посмотрите на такие инструменты, как Sonarqube , Код климат или Кодекс Анкет

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

Автоматизированные тесты

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

Такие практики, как «непрерывная доставка», возможны только с хорошим автоматическим набором тестов.

Автоматизированные тесты (более конкретные модульные тесты) также являются отличным драйвером для написания лучшего кода, поскольку вы будете «вынуждены» написать более простой и более развященный код и применять популярные шаблоны проектирования, такие как инъекция зависимостей и другие принципы S.O.L.I.D, чтобы для этого быть тестируемым.

Тесты также могут использоваться в качестве формы документации существующих функций и всех возможных сценариев и вариантов использования.

Начните с модульных тестов, за которыми следуют интеграцию/сервисные тесты и добавьте пару тестов E2E, просто чтобы гарантировать, что ваше приложение может обслуживать запросы.

Создайте простой тест «Hello World» для каждого типа перед началом добавления функций. Это гарантирует, что у вас есть все настройки инфраструктуры, чтобы выполнить эти тесты, что делает их быстрее, чтобы добавить больше, поскольку вы продолжаете разрабатывать новые функции.

Автоматизированные тесты — очень широкая и интересная тема. Если вы хотите лучше понять, какой тип тестов вы должны пройти в своем приложении и как их структурировать, следующие статьи — хорошее начало:

Среда разработки

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

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

Я считаю, что вы сможете настроить среду разработки, просто выполнив одну команду. Благодаря таким инструментам, как Docker и Docker Compose Вместе с сценарием Makefile или некоторыми раковинами это намного проще сделать в настоящее время.

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

Вы должны стремиться к тому, чтобы ваша местная среда была ближе всего к производственной среде. Если вы используете Docker в производстве, вы можете воспользоваться Docker Multi Stage Builds и используйте те же базовые изображения, которые вы будете использовать в производстве.

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

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

Но среда разработки касается не только самого применения. Потратьте время, чтобы точно настроить свой редактор кода/IDE и любые вспомогательные инструменты (например: Live Reloading). У многих IDE есть файлы конфигурации, которыми вы можете поделиться с помощью управления версиями с вашей командой, поэтому глобальные конфигурации хранятся в синхронизации и согласованы между всеми членами вашей команды.

Трубопровод доставки

Давайте поговорим о недостающей части в головоломке, где мы клейте все, что мы обсуждали, пока сейчас вместе, что является конвейером доставки.

Поручение доставки определяет все этапы, которые ваш код должен будет передать от коммита в VCS к производству.

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

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

Позже, и в зависимости от ваших потребностей вы можете подумать, добавляя больше этапов, например, тесты безопасности и производительности.

Построить стадию

Ничего не задумывается об этом этапе. Этот этап берет ваш код из системы управления версиями и создает развертываемый артефакт. Это может быть изображение Docker, Tarball, RPM и т. Д., Подавив сгенерированный артефакт к некоторому репозиторию артефакта.

Статический анализ этапа

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

Унидимые тесты стадии

Этот этап должен запустить тесты вашего устройства приложения. Даже если у вас просто есть тест «Hello World», вначале, если он уже доступен в процессе работы, позволит вам строить его намного быстрее, так как инфраструктура для запуска тестов уже будет на месте.

Интеграционные тесты стадии

На этом этапе будет запускать ваши интеграционные тесты (например: тесты базы данных) или сервисные тесты.

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

Большинство популярных инструментов CI/CD в настоящее время поддерживают Docker, поэтому, например, очень легко породить контейнер MySQL, чтобы использовать его ваши тесты.

Стадия принятия

На этом этапе ваше приложение должно быть развернуто в некоторой стадии, где мы можем запустить некоторые автоматизированные тесты высокого уровня, такие как сквозные тесты (E2E).

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

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

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

Этап развертывания

После того, как ваш код пройдет все предыдущие этапы, он должен быть готов к развертыванию в производство.

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

Есть много отличных инструментов для определения вашего конвейера доставки. Дженкинс все еще много используется на предприятии, но я предпочитаю более современные инструменты, такие как Circleci , Gitlab или Drone Ci Анкет

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

Чтобы узнать больше о том, как правильно построить конвейер непрерывной доставки, взгляните на эти статьи:

Дополнительный: Ищите возможности автоматизации

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

Вывод

На поддержание и качество проекта будет сильно повлиять, как вы его начинаете.

Гораздо проще начать создавать проект с учетом качества, чем добавить его позже.

Определение жизненного цикла разработки программного обеспечения, включая GIT-Flow, руководящие принципы взносов, руководящие принципы по стандартам кодирования, надежный конвейер доставки и отличная документация являются важными первыми шагами для успешного, обслуживания и без ошибок.

Нужно ли мне все это для всех видов проектов? Как и все в разработке программного обеспечения, нет «одного размера, подходит для всех». Есть много факторов, которые следует учитывать. Очень маленькое приложение или MVP? возможно, нет. Проект, который вы хотите быть твердым и/или, который имеет ожидания, определенно станет большим масштабным.

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

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

И с некоторым опытом и хорошим инструментом, в этой статье на самом деле не потребуется столько дополнительного времени и усилий.

Спасибо за чтение.

Стоит прочтения

Оригинал: «https://dev.to/brpaz/how-to-start-a-software-project-with-a-quality-mindset-3e7i»