В предыдущем посте мы загрузили некоторые мысли о том, какие знания пригодились разработчикам в работе. Кроме того, мы обсудили, что у каждой части знаний есть свои особенности (когда и как они появляются, как часто обновляются, насколько важно уведомлять аудиторию и т. д.).
В этом посте мы предлагаем картографию 20 различных типов источников знаний и информации, с которыми разработчики взаимодействуют во время своей работы. Это может помочь вам структурировать процесс адаптации новых разработчиков в вашей команде и обеспечить им доступ к данным, необходимым им для достижения успеха. Или, если вы только что присоединились к новой компании, вы можете использовать его в качестве контрольного списка, чтобы проверить, есть ли у вас все необходимые права доступа. Это не исчерпывающий список, и вы можете указать дополнительные источники знаний — дайте нам знать! Также мы перечислим несколько примеров инструментов; существуют еще некоторые.
# 1 Практические процедуры, учебные пособия и руководства по началу работы
Полезно для настройки программного обеспечения или проекта на ноутбуке, при настройке вашей IDE в первый раз, когда нам нужно подключиться к удаленной базе данных, загрузить новый проект в соответствии с определенным скелетом или как отправить новую версию приложения. . Небольшая группа поддерживает эту документацию, которая часто является одноразовой процедурой чтения, поскольку она не понадобится вам каждый день. Но мы счастливы иметь его, когда он нам нужен. Мы также называем их вечнозеленым контентом.
- Инструменты: Confluence, Notion.
# 2 Лучшие практики кодирования
Жесты разработчиков при написании исходного кода в соответствии с командными практиками. Речь идет о правильном написании исходного кода в контексте разработчика. Эти лучшие практики должны быть точно определены в команде и на уровне компании, постоянно поддерживаться и регулярно обсуждаться. Интеграция во время код-ревью и в IDE обязательна.
- Инструменты: Promyze.
#3 Документация по коду
Получите представление о кодовой базе, подразделе или конкретном фрагменте кода. Это может помочь понять сложное поведение, прошлый неинтуитивный технический выбор или детали реализации, требующие пояснений. Используйте его осторожно, так как лучше всего иметь понятный код, в котором комментарии не приносят никакой пользы. Эта документация по коду обычно зависит от контекста, и разработчики должны поддерживать ее в актуальном состоянии.
- Инструменты: Swimm, Read the Docs.
#4 Наборы тестов
Тестовый код — это мощная документация кода, и мы могли бы процитировать его в предыдущем пункте № 3. Чтение тестового кода дает обзор основных методов вашего программного обеспечения и дает конкретные примеры использования, особенно если ваша команда пишет тесты, используя шаблоны «Дано/Когда/Тогда» или «Упорядочить/Действовать/Утвердить». Если вы погружаетесь в новый модуль, поиск тестов — отличное начало для более близкого знакомства с кодовой базой.
- Инструменты: ваш любимый тестовый фреймворк, JUnit, Mocha, PyTest.
#5 Документация по API
Неизбежный, он поможет вам понять, как использовать SDK или API, узнать о доступных службах и их назначении, а также о том, как программно взаимодействовать с ними. Примеры кода дают вам уверенность в использовании API и обработке ситуаций, когда возникают ошибки. На первый взгляд вы должны определить, удовлетворяет ли API ваши потребности. В противном случае идите своей дорогой.
- Инструменты: Swagger, Doxygen, apiDoc, Readme.
#6 Проблемы с качеством кода
Проверьте, содержит ли исходный код проблемы с безопасностью, неприятные запахи, проблемы с форматированием, улучшения читабельности и многое другое, с помощью статического анализа исходного кода. Вы можете оставить отзыв о своей IDE во время проверки кода и общего обзора на специальной панели инструментов. Эти линтеры доступны для всех языков программирования и помогают поддерживать согласованность синтаксиса кода.
- Инструменты: SonarQube, Codiga, EsLint.
#7 Пользовательские истории
Помогите понять будущую функцию, которую нужно реализовать, ее намерения и цель для пользователей. Пользовательская история (US) содержит требования и определяет критерии приемлемости, чтобы прояснить, как считать функцию готовой. США — это коммуникационный мост между владельцем продукта и разработчиком, так как весь контент записывается. Обязателен для начала кодирования!
- Инструменты: Jira, Trello, Asana.
#8 Отчеты об ошибках
Они преследуют две основные цели: 1) получить информацию о недавно обнаруженной ошибке, о том, как она влияет на пользователей, каковы ее последствия, какие доступны сообщения об ошибках и как ее воспроизвести; 2) найти информацию о ранее исправленной ошибке, как в настоящее время мы исследуем аналогичный; вы ищете, как эта предыдущая ошибка была исправлена, чтобы помочь вам в вашей работе. Они имеют решающее значение для обеспечения исправления ошибки и реализации контрмер.
- Инструменты: Linear, Jira.
# 9 Исполняемые спецификации
Behavior-Driven Development (BDD) помогает генерировать сценарии, которые иллюстрируют варианты использования бизнес-доменов, на основе которых можно установить бизнес-правила. Бизнес-эксперты, разработчики и заинтересованные стороны (например, инженеры по обеспечению качества) совместно разработали конкретные примеры поведения. Вы можете сформулировать эти примеры с помощью синтаксиса Gherkin. Во время адаптации эти примеры помогут вам ознакомиться с бизнес-сферой. Он управляет процессом кодирования, особенно при использовании TDD.
- Инструменты: Cucumber, Cukedoctor.
#10 Архитектурные схемы
Этот высокоуровневый материал может обобщить общую картину программного проекта, основные компоненты и то, как они взаимодействуют друг с другом. Это полезно при адаптации нового проекта, чтобы лучше понять, как все работает. Потоки диаграмм или схемы UML также могут документировать программное обеспечение на высоком уровне абстракции. Это может быть неуместно для некоторых программ, поскольку вы можете самостоятельно задокументировать адекватную архитектуру кода. Ретро-инжиниринг и анализ кода также могут дать представление об архитектуре кода.
- Инструменты: Notion, CodeSee.
#11 Обзор технического долга
Я использую сокращенный термин технический долг, чтобы рассмотреть части кода, которые требуют переработки — не только потому, что код сложен, но и потому, что реализация, как она есть, может поднимать вопросы в краткосрочной/среднесрочной перспективе, если ничего не изменится. Обзор частей исходного кода, помеченных как технический долг, может помочь определить приоритеты исправления и оценить усилия по предоставлению.
- Инструменты: StepSize, CodeScene.
#12 Ответы на техническую проблему
Нелегко классифицировать, но здесь я имею в виду каждую проблему блокировки, с которой мы сталкиваемся при написании кода или создании приложения, например, проблему компиляции. Когда вы застряли и не можете найти ответ в документации, вы можете использовать асинхронные каналы, чтобы спросить, сталкивался ли кто-нибудь с похожей проблемой. Ответ разблокирует рабочий процесс, и вы сможете возобновить свою работу. Вы можете найти ответ внутри компании или через Интернет.
- Инструменты: StackOverflow, Slack, CodeStream.
# 13 Отчеты об архитектурных решениях (ADR)
ADR — это документ, в котором фиксируются важные решения, такие как выбор дизайна, компромиссы и обоснования, связанные с архитектурой программного обеспечения. Он служит исторической записью и обеспечивает прозрачность и подотчетность архитектурных решений. В ADR также содержится информация о его контексте и последствиях. Полезно, когда вы присоединяетесь к проекту, чтобы получить представление об эволюции архитектуры.
- Инструменты: файлы Markdown, встроенные в репозиторий Git.
# 14 Прототипы пользовательского интерфейса
Фронтенд-разработчики заинтересованы в использовании прототипов пользовательского интерфейса, которые отражают ожидания в отношении пользовательского интерфейса и экранов. Это помогает понять рабочий процесс пользователя и дает четкое представление о взаимодействии пользователей с разрабатываемой функцией. Они необходимы для начала реализации дизайна, доступа к элементам CSS и получения результата, точно соответствующего прототипам.
- Инструменты: Figma, Adobe XD.
# 15 Дизайн-система
Система для централизации и повторного использования компонентов, связанных с дизайном продукта, домена или компании. В основном полезно для фронтенд-разработчиков, чтобы убедиться, что исходный код поставляется с современными элементами дизайна (логотип, шрифт, значки и т. д.). Известен как центральное место, где мы можем найти информацию, связанную с дизайнерскими решениями.
- Инструменты: сборник рассказов.
# 16 Журналы выполнения
Они дают ценную информацию о поведении вашего кода во время выполнения. Они помогут вам изучить сообщение об ошибке или проанализировать производительность вашего программного обеспечения. Журналы необходимы для наблюдения за нашим программным обеспечением, и они дают ценную информацию о том, что происходит на практике (сколько раз вызывается служба, как долго длится выполнение службы и т. д.). Все разработчики должны иметь доступ к журналам в рабочей среде.
- Инструменты: Logtail, Logz.io, Loggly.
#17 История кода
Полезно, когда вам нужно понять, как фрагмент кода пришел к своему текущему состоянию, или если вы понимаете, что состояние изменилось с момента, когда вы в последний раз видели этот код, и хотели бы знать, что произошло. Управление версиями с помощью Git обеспечивает отличную поддержку и иногда приводит вас к археологическим работам. Вы можете определить последнего редактора кода и связаться с ним/ней для дальнейших вопросов. Предыдущие коммиты также дают представление о текущей работе.
- Инструменты: любой клиент Git, GitHub, GitKraken, GitLab.
# 18 Статусы сборки
Попался к разработчику, чтобы проверить, не вызывает ли слияние веток каких-либо проблем, или получить дополнительную информацию о сломанной сборке (вероятно, из-за неудачного теста). Эта информация считывается по запросу и обычно не при каждом нажатии на репозиторий Git, поскольку системы оповещения отправляют уведомления, когда возникает проблема (а не когда все в порядке). Статус сборки указывает, готов ли код к производству.
- Инструменты: Jenkins, GitLab CI, GitHub Actions.
# 19 Учебные ресурсы
Разработчики могут учиться на своих текущих проектах и параллельно развивать личные навыки в конкретных концепциях. Ресурсы для электронного обучения позволяют проводить асинхронные учебные занятия в удобное для вас время. Практические занятия полезны при обучении новому языку, в котором вы хотели бы продвинуться. Например, мы также включаем сообщения в блогах, размещенные на внутренних каналах в рамках Практического сообщества. Это часть процесса непрерывного совершенствования и культуры обучения.
- Инструменты: Pluralsight, Udemy, внутренние вики, книги.
#20 Документация по продукту
Часто забываемый, он по-прежнему дает ценную информацию о том, как ведет себя программное обеспечение, и помогает понять различные варианты использования приложения и рабочие процессы пользователей. Это имеет смысл, если программное обеспечение достаточно сложное. Технические писатели ведут эту документацию; вы могли бы сделать это в каком-то контексте.
- Инструменты: GitBook, Intercom, Zendesk.
Подведение итогов
Мы закончили с этим списком! Последний вопрос к вам: к скольким источникам из этого списка у вас есть доступ? У вас есть еще предложения? Мы будем рады добавить их, особенно если вы регулярно сталкиваетесь с какой-либо информацией или знаниями, не упомянутыми в этом посте. Спасибо!
