В Силиконовой долине, если вы случайно остановите программиста на улице и спросите: «Прежде чем начать проект, что вы должны сделать?» девять из десяти, вероятно, ответят: «Напишите дизайн-документ». А является общим файлом среди инженеров, который описывает функцию, которая должна быть реализована до того, как какой-либо код будет написан, как в Дизайнные документы часто состоят из нескольких разделов: design document (design doc) Этот пример Этот пример Обзор: Несколько простых предложений, описывающих функцию, которая будет реализована. Мотивация: Почему мы используем эту функцию? Превью: как будет выглядеть функция после ее внедрения? Технический выбор: Какие технические варианты мы должны реализовать эту функцию? Каковы плюсы и минусы каждого? Какой мы выбрали и почему? Необходимые детали реализации: Перечень шаблонов кода, как тестировать, как писать журналы и т. Д. Важно отметить, что проектный документ должен оставаться на высоком уровне; конкретная реализация - это работа кода. Первичный автор составляет проектный документ, а их коллеги общаются с автором, комментируя документ. Весь этот процесс общения зачастую длится несколько дней или даже недель. Как только автор и коллеги соглашаются на содержание документа, он может быть объединен в кодовую базу. Этот процесс включения проектных документов в проекты предлагает многочисленные преимущества. Если вы можете сформулировать свои идеи кратко, логически ясным языком, это указывает на глубокое понимание реализации функции. Наоборот, если вы не можете даже выразить то, что вы намереваетесь написать, то реализация функции будет еще сложнее. Ваши коллеги, комментируя ваш проектный документ, также помогут вам пересмотреть ваши идеи, обнаружить проблемы заранее, указать на логические недостатки и даже предложить лучшие методы реализации (я неоднократно обнаруживал, что коллеги вокруг меня последовательно придумывают лучшие решения и выявляют логические пробелы в моем мышлении). Особенно опытные программисты в команде могут сэкономить вам значительное количество времени развития позже с простыми предложениями. First, design documents help you clarify your thoughts. Они делают техническое мышление каждого прозрачным, а кодовая база становится более поддающейся поддержанию.Если проектный документ одобрен всеми, то у каждого будет больше собственности на весь проект и будет больше желания помочь улучшить качество кода, что приведет к высокому общему инженерному качеству для проекта. Second, design documents help the entire team reach a consensus. Новые члены команды и коллеги из других команд могут легко получить понимание на высоком уровне всей кодовой базы через документы дизайна.Когда кто-то хочет понять состояние проекта, нет ничего более удовлетворительного, чем просто отправить им ссылку. Third, design documents are an excellent supplement to code. По сравнению с длительными встречами, дизайн-документы позволяют коллегам (в разных часовых поясах) спокойно отражать самостоятельно в свое подходящее время, усовершенствовать свои мысли и предоставлять отзывы автору. Предразработанные дискуссии между коллегами могут эффективно пересмотреть весь дизайн-подход, значительно уменьшая риск дефектных дизайнов (поверьте мне, я не раз был ленивым и непосредственно написал код, только чтобы найти дни моего развития оказались бесполезными). Во время разработки, поскольку коллеги уже понимают концепцию дизайна, обзоры кода становятся более простыми. Если проблемы возникают во время предразработки, разработчики также могут более легко получить помощь от коллег. После разработки, дизайн-документы также обеспечивают основу для всей команды для проведения технических пост-мортам. Fourth, design documents help teams save time. Коллеги, участвующие в дискуссиях, часто интересуются проблемой, которую проектный документ стремится решить. Fifth, design documents are excellent for organizing teams. Дизайнные документы часто отражают инженерную грамотность автора, ясность мышления при решении проблем и способность решать важные проблемы. Sixth, design documents are excellent material for promotion. Поскольку написание дизайнерских документов приносит столько преимуществ команде, почему не все следуют этой практике? «Письмо дизайнерских документов — это слишком много хлопот, может быть, я только начну кодировать сначала?» Если вы обнаружите, что дизайн-документы трудно написать, это указывает на то, что автор недостаточно хорошо понимает проблему, и выбранный ими метод реализации, вероятно, неправилен. «Если бы я пропустил написание документа, я уже закончил бы код». Всё в умеренности. Нужен ли проектный документ, зависит от долгосрочного качества кода и поддержания проекта. Если функцию легко реализовать и ее логика проста, возможно, достаточно простого создания проблемы для описания функции, а поддержание кода и выравнивание команды можно достичь через обзор кода. Однако, для сложных функций, написание проектного документа все равно рекомендуется. «Я хорош в этом, смотрите, как я реализую его напрямую и впечатляю моих коллег». В то время как наличие областей экспертизы является плюсом, общение внутри команды также важно. С одной стороны, если коллеги не понимают подход автора, им трудно проводить обзоры кода; с другой стороны, держатель кода и автор часто не являются одним и тем же человеком. Стремитесь изменить эти восприятия, выйдите из своей зоны комфорта, попробуйте начать писать дизайн-документы и активно участвуйте в комментировании других дизайнерских документов. Однажды я пожаловался коллеге: «Я действительно не могу понять код других людей, особенно на таких языках, как Python, которые легко писать, но трудно читать».Коллеги ответили: «Не волнуйтесь, они тоже не могут понять ваш».Я смеялся тогда, думая: если бы не было дизайнерских документов, чтобы держать всех на высоком уровне, и каждый только общался, читая друг друга код, насколько неэффективны были бы операции команды?