Как написать предварительную документацию по техническим решениям в Zhengcaiyun

牧羊.png

Это 126-я оригинальная статья без воды.Если вы хотите получить больше оригинальных статей, выполните поиск в общедоступном аккаунте и подпишитесь на нас~ Эта статья была впервые опубликована в блоге Zhengcaiyun:Как написать предварительную документацию по техническим решениям в Zhengcaiyun

предисловие

Энциклопедия Baidu определяет компьютерное программное обеспечение следующим образом: «Компьютерное программное обеспечение (программное обеспечение, также известное как программное обеспечение) относится к программе и ее документации в компьютерной системе. Программа представляет собой описание объектов обработки и правил обработки вычислительных задач; документы используются для облегчить понимание программы. Необходим описательный материал. Для работы программы должны быть загружены в машину, а документация, как правило, предназначена для просмотра людьми, а не обязательно в машину».

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

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

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

из.

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

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

Через некоторое время Сяо Мин получил еще один запрос на добавление некоторых функций в модуль, разработанный в прошлый раз. При открытии кода Сяо Мин потерял сознание. Я давно забыл логику предыдущего кода. Столкнувшись с кодом, который я не могу понять, я начал мучить себя "Что толку от этого метода? Почему у этого метода так много параметров? Почему логика такая сложный?», «Код, прыгающий между разными страницами, и код, который выглядит почти одинаково, в чем их логика?», «Почему столько флажков, столько магических чисел, что они делают?». Аннотации что-ли не существует, а если и есть, то не понятно о чем речь.

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

Вышеупомянутая история основана на реальных событиях.

Я думаю, что написание документов с техническими решениями может решить некоторые проблемы Сяо Мина: «Составьте план, прежде чем действовать, дважды подумайте, прежде чем действовать», — все это говорит об этом. Конечно, написание документации — не панацея. Сравнивая бэкенд, вы обнаружите, что они сделают дизайн решения до написания кода.Кажется, что времени разработки бэкенда предостаточно или техническое решение фронтенда не стоит упоминать? Конечно нет. Разработка схемы является передовой практикой в программной инженерии.Обычно общая структура программного обеспечения отражается в процессе создания технических схем.После сортировки основного процесса его можно в основном реализовать в коде. Другими словами, хорошее техническое решение может отражать логику окончательного кода, и вы можете знать, как писать код, глядя на решение. Это предотвращает проблему путаницы в структуре кода в процессе написания кода при его написании и изменении.

Как написать технический план

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

Бизнес-модель может быть последовательной на переднем и заднем концах, ведь мы решаем одну и ту же бизнес-задачу. Но есть и небольшие отличия: некоторые данные на фронтенде не берутся из бэкенда, или их не обязательно получать из бэкенда, это нужно учитывать при проектировании. Например, одна и та же страница H5 должна отображать разные цвета темы в общедоступной учетной записи WeChat и DingTalk.

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

Back-end уделяет больше внимания логической архитектуре и схеме развертывания, потому что back-end должен быть сервисно-ориентированным, а определение границ между сервисами должно быть очень четким и конкретным. Фронтенд соответствует микросервису, он должен быть компонентом, но охват компонента слишком широк.От кнопки до страницы, его можно назвать компонентом, и даже подприложением в горячем микро- фронтенд также может стать компонентом, поэтому компоненты фронтенда нужно разделить на страницы, модули, элементы управления и другие единицы разного уровня инкапсуляции. В процессе этого деления естественно отражается логическая структура. В то же время задачи, решаемые интерфейсом и сервером, разные, что приводит к разным проблемам. Интерфейсу необходимо обратить внимание на восстановление страницы, например, насколько абстрактными должны быть элементы страницы и насколько стиль следует использовать повторно, это не учитывается серверной частью.

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

Что касается схемы реализации, то задачи front-end и back-end немного отличаются, back-end больше касается интеграции между системами и совместимости старых данных. Внешний интерфейс должен учитывать разницу между настольными и мобильными устройствами или интеграцию различных каналов, таких как WeChat и Alipay.

После сравнения постепенно стал ясен контекст фронтальных технических решений. В сочетании с приведенной выше методологией следующее объяснение фактического случая.

Кейсы технических решений

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

Глава 1, Обзор 1. Как правило, кратко описываются предыстория и ценность проекта. Смысл или мотивация выполнения чего-либо очень важны. Как правило, это можно резюмировать из документа с требованиями. Затем объясните некоторые имена собственные, которые необходимо использовать в следующих документах, и очень важно достичь консенсуса по некоторым существительным.

Глава 2. Сопутствующая документация.收集版本开发的相关文档，这样开发的时候只要通过这一个前端技术方案文档，就能找到所有的文档，有时候我也会把这些网页整理到一个浏览器书签文件夹里。

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

Оценка времени заключается в разделении основных функций на странице в соответствии с размерами страницы и оценке времени. Оценка времени будет более точной на основе статической демонстрации и взаимодействия JS. Затем время умножается на коэффициент 1,3 (поскольку каждую неделю проводятся разные встречи, а общение требует времени).

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

**Глава четвертая, Общий проект. ** Перечислите спецификации разработки и логическую архитектуру. Картинка стоит тысячи слов, и настоятельно рекомендуется заменить логику, связанную со временем, картинкой. Блок-схемы, диаграммы последовательности и диаграммы состояний для документирования ваших технических решений~~полный стиля~~Прозрачный.

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

**Глава 5, Рабочий проект. **Эта глава является центром всего технического решения, включая четыре подраздела: описание функций, описание процесса, детальный проект модуля и внешние зависимости.

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

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

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

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

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

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

Наконец, я рекомендую два полезных инструмента для рисования:

plantuml: рисуйте диаграммы UML, используя простые текстовые описания.
drawio: Интернет-сайт для рисования иконок

Оба вышеупомянутых инструмента имеют соответствующие расширения vscode. (processonЭто также очень полезно, но, к сожалению, бесплатная версия может сохранить только 9 графиков)

Суммировать

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

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

Учитель Кай-Фу Ли в «Вершине прилива»в преамбулеСказал: «Я знаю многих ведущих инженеров, но я знаю очень мало выдающихся инженеров с сильными способностями к повествованию». Выражение является одной из важных мягких сил инженеров-разработчиков программного обеспечения.Как передовая практика разработки программного обеспечения, проектирование схем по-прежнему очень необходимо в процессе разработки интерфейса, так почему область интерфейса не обращает внимания на этот вопрос для долгое время, я думаю, есть следующие причины:

Дизайн опирается на технологические возможности, а внешний стек технологий меняется слишком быстро, сегодняшние процедуры проектирования завтра могут быть неэффективными;
Front-end бизнес меняется слишком быстро, после полугодовой итерации первая версия решения может не отражать существующую логику кода;
Front-end бизнес-процесс и процесс взаимодействия намного сложнее, чем back-end, а возможность повторного использования оставляет желать лучшего, требует много времени на обдумывание и организацию, предъявляет относительно высокие требования к возможностям абстракции;
Эффективность front-end разработки высокая, не будет исторической нагрузки, а иногда эффективность прямого рерайта выше;
язык иIDEПоддержка рефакторинга намного лучше, чем интерфейс;
Задний конец относительно зрелый, такой как общийmvcРасслоение — это почти договоренность, хочешь интерфейс?modelслой или нетserviceСлои должны обсуждаться независимо от того,redux,reduxКакие данные хранить, у всех разное понимание;
Абстрактное мышление и инженерные способности фронтенд-персонала, как правило, слабее, чем у бэкэнда;

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

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

Последующее уведомление

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

работы с открытым исходным кодом

Zhengcaiyun интерфейсный таблоид

адрес с открытым исходным кодомwww.zoo.team/openweekly/(На главной странице официального сайта таблоида есть группа обмена WeChat)

Плагин выбора товара

адрес с открытым исходным кодомGitHub.com/Chinese Patent Medicine-Inc/Reservoir…

Карьера

ZooTeam, молодая, увлеченная и творческая команда, связанная с отделом исследований и разработок продукции Zhengcaiyun, базируется в живописном Ханчжоу. В настоящее время в команде более 60 фронтенд-партнеров, средний возраст которых составляет 27 лет, и почти 40% из них — инженеры полного стека, настоящая молодежная штурмовая группа. В состав членов входят «ветераны» солдат из Ali и NetEase, а также первокурсники из Чжэцзянского университета, Университета науки и технологий Китая, Университета Хандянь и других школ. В дополнение к ежедневным деловым связям, команда также проводит технические исследования и фактические боевые действия в области системы материалов, инженерной платформы, строительной платформы, производительности, облачных приложений, анализа и визуализации данных, а также продвигает и внедряет ряд внутренних технологий. Откройте для себя новые горизонты передовых технологических систем.

Если вы хотите измениться, вас забрасывают вещами, и вы надеетесь начать их бросать; если вы хотите измениться, вам сказали, что вам нужно больше идей, но вы не можете сломать игру; если вы хотите изменить , у вас есть возможность добиться этого результата, но вы не нужны; если вы хотите изменить то, чего хотите достичь, вам нужна команда для поддержки, но вам некуда вести людей; если вы хотите изменить установившийся ритм, это будет "5 лет рабочего времени и 3 года стажа работы"; если вы хотите изменить исходный Понимание хорошее, но всегда есть размытие того слоя оконной бумаги.. , Если вы верите в силу веры, верьте, что обычные люди могут достичь необыкновенных вещей, и верьте, что они могут встретить лучшего себя. Если вы хотите участвовать в процессе становления бизнеса и лично способствовать росту фронтенд-команды с глубоким пониманием бизнеса, надежной технической системой, технологиями, создающими ценность, и побочным влиянием, я думаю, что мы должны говорить. В любое время, ожидая, пока вы что-нибудь напишете, отправьте это наZooTeam@cai-inc.com