Привычки повышения эффективности инженерных команд (часть 1): проектные документы
10 июля 2025 г.В Силиконовой долине, если вы случайным образом остановите программиста на улице и спросите: «Прежде чем начать проект, что вы должны делать?» Девять из десяти, скорее всего, ответит: «Напишите док -дизайн». Итак, почему дизайнерские документы так важны? Давайте начнем с определения того, что такое дизайнерский документ.
АДизайн документ (Design Doc)является общим файлом среди инженеров, в котором описывается функция, которая будет реализована до написания какого -либо кода, как в
- Обзор: Несколько простых предложений, описывающих функцию, которая будет реализована.
- Мотивация: Почему мы реализуем эту функцию?
- Предварительный просмотр: Как будет выглядеть функция после реализации?
- Технический выбор: Какие технические варианты мы должны реализовать эту функцию? Каковы плюсы и минусы каждого? Какой из них мы выбрали и почему?
- Необходимые данные реализации: Сообщите шаблоны кода, как протестировать, как писать журналы и т. Д. Важно отметить, что проектный документ должен оставаться высоким уровнем; Конкретная реализация является задачей кода.
Основной автор создает проектный документ, и их коллеги общаются с автором, комментируя документ. Весь этот процесс общения часто длится несколько дней или даже недель. Как только автор и коллеги согласятся с содержанием документа, его можно объединить в кодовую базу. Это также знаменует собой начало проекта, описанного в проектном документе.
Этот процесс включения проектных документов в проекты предлагает многочисленные преимущества.
Во -первых, дизайнерские документы помогают вам прояснить ваши мысли.Если вы можете сформулировать свои идеи на лаконичном, логически четком языке, это указывает на глубокое понимание реализации функции. И наоборот, если вы даже не можете выразить то, что вы собираетесь написать, то реализация функции будет еще сложнее. Ваши коллеги, комментируя ваш проектный документ, также помогут вам просмотреть ваши идеи, заранее обнаружить проблемы, указать логические недостатки и даже предлагать лучшие методы реализации (я неоднократно обнаружил, что коллеги вокруг меня постоянно придумывают решения и выявляют логические пробелы в моем мышлении). Особенно опытные программисты в команде могут сэкономить вам значительное время разработки с простыми предложениями.
Во -вторых, дизайнерские документы помогают всей команде достичь консенсуса.Они делают все техническим мышлением прозрачным, и кодовая база становится более поддерживаемой. Если каждый документ одобрен всеми, то каждый будет иметь больше владения всем проектом и будет более готовым помочь улучшить качество кода, что приведет к высокому общему качеству инженеров для проекта.
В -третьих, дизайнерские документы являются отличным дополнением к коду.Новые члены команды и коллеги из других команд могут легко получить понимание высокого уровня всей кодовой базы с помощью дизайнерских документов. Когда кто -то хочет понять статус проекта, нет ничего более удовлетворяющего, чем просто отправлять им ссылку.
В -четвертых, дизайнерские документы помогают командам сэкономить время.По сравнению с длинными встречами, дизайнерские документы позволяют коллегам (в разных часовых поясах) спокойно отражаться независимо в их собственное подходящее время, усовершенствовать свои мысли и предоставлять отзыв автору. Обсуждения перед разработкой между коллегами могут эффективно пересмотреть весь подход к проектированию, значительно снижая риск некорректных дизайнов (поверьте мне, я более одного раза был ленивым и непосредственно писал код, только чтобы обнаружить, что дни моего развития оказались бесполезными). Во время разработки, поскольку коллеги уже понимают концепцию дизайна, обзоры кода становятся проще. Если проблемы возникают во время предварительного развития, разработчики также могут легче получить помощь от коллег. После разработки дизайнерские документы также обеспечивают основу для всей команды для проведения технических посмертных средств.
В -пятых, дизайнерские документы отлично подходят для организации команд.Коллеги, которые участвуют в дискуссиях, часто заинтересованы в проблеме, которую предназначен для проектного документа. Благодаря дизайнерским документам они могут быстро сформировать небольшие команды и эффективно выполнять задачи с достаточной страстью.
В -шестых, дизайнерские документы являются отличным материалом для продвижения по службе.Проектные документы часто отражают инженерную грамотность автора, ясность мышления в решении проблем и способность решать важные проблемы.
Поскольку написание дизайнерских документов приносит так много преимуществ для команды, почему все не следуют этой практике? Из моих наблюдений это может быть связано со следующими заблуждениями:
- «Письменные дизайнерские документы - это слишком много проблем, может быть, я просто начну кодировать сначала?» Если вы обнаружите, что дизайнерские документы трудно написать, это указывает на то, что автор недостаточно полностью понимает проблему, и выбранный метод реализации, вероятно, неверный. Написание дизайнерских документов, безусловно, требует больших усилий изначально, но, как упоминалось выше, эти инвестиции ценны в долгосрочной перспективе.
- «Если я пропущу написание документа, я бы уже закончил код». Все в меру. Независимо от того, требуется ли проектный документ, зависит от долгосрочного качества и обслуживания кода проекта. Если функция проста в реализации, а ее логика проста, возможно, просто просто создать проблему для описания этой функции, а поддержание кода и выравнивание команды может быть достигнуто посредством обзоров кода. Однако для сложных функций написание проектного документа все еще рекомендуется.
- «Я хорош в этом, смотрю, как я реализую это напрямую и впечатляю моих коллег». Несмотря на то, что наличие областей опыта является плюсом, общение в команде одинаково важно. С одной стороны, если коллеги не понимают подхода автора, им трудно провести обзоры кода; С другой стороны, сопровождающий кода и автор часто не один и тот же человек. Если идеи автора не сохраняются посредством документации, а код является сложным, обслуживание всего проекта снизится.
Стремитесь изменить эти восприятия, выйдите из своей зоны комфорта, постарайтесь начать писать дизайнерские документы и активно участвовать в комментировании документов других дизайнерских документов. Вы обнаружите, что ваш вклад в команду будет размножаться.
Анекдот: Однажды я пожаловался коллеге: «Я действительно не могу понять код других людей, особенно на таких языках, как Python, которые легко написать, но трудно читать». Коллега ответил: «Не волнуйся, они тоже не могут понять тебя». Тогда я засмеялся, думая: если бы не было дизайнерских документов, чтобы все выровнялись на высоком уровне, и все сообщали только путем чтения кода друг друга, насколько неэффективными будут операции команды?
Оригинал