Поможет вам приступить к проектированию переднего плана (2): унифицированная спецификация

спецификация кода

Спецификации кода относятся к правилам, которым должны следовать программисты при написании кода.Цель спецификаций — позволить программистам писать легко читаемый и поддерживаемый код.

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

Помимо двух только что упомянутых моментов, спецификация Unicode имеет и другие преимущества:

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

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

Как разрабатывать спецификации кода

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

формат кода

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

Соглашения об именах

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

const smallObject = {} // 驼峰式，首字母小写
const SmallObject = {} // 帕斯卡式，首字母大写
const strName = 'strName' // 匈牙利式，前缀表示了变量是什么。这个前缀 str 表示了是一个字符串

Имена переменных и имена функций имеют разное значение.

Смысл именования переменных состоит в том, чтобы указать, что эта переменная «является» и, как правило, именуется существительными. Смысл именования функций состоит в том, чтобы указать, что функция «делает», и имеет тенденцию называться по структуре «глагол-объект» (структура «глагол-объект»doSomething).

// 变量命名示例
const appleNum = 1
const sum = 10

// 函数命名示例
function formatDate() { ... }
function toArray() { ... }

Поскольку омофонов пиньинь слишком много, не используйте пиньинь для имени.

Примечания к документации

Комментарии к документации относительно просты, например, однострочные комментарии с использованием//, использование многострочных комментариев/**/.

/**
 * 
 * @param {number} a 
 * @param {number} b 
 * @return {number}
 */
function add(a, b) {
    return a + b
}

// 单行注释
const active = true

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

Вот некоторые из наиболее известных спецификаций кода JavaScript:

• airbnb (английская версия, 101 тысяча звезд),airbnb-китайская версия
• стандартная (24,5k звезда) китайская версия
• Спецификация кодирования интерфейса Baidu 3,9 тыс. звезд

Существует также множество спецификаций кода CSS, например:

• styleguide 2.3k star
• spec 3.9k star

Спецификация аннотации

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

Если написать такую ​​функцию:

function timestampToDate(timestamp = 0) {
    if (/\s/.test(timestamp)) {
        return timestamp
    }

    let date = new Date(timestamp)
    return date.toLocaleDateString().replace(/\//g, '-') + ' ' + date.toTimeString().split(' ')[0]
}

function objToUrlParam(obj = {}) {
    let param = ''
    for (let key in obj) {
        param += '&' + key + '=' + obj[key]
    }
    
    return param? '?' + param.substr(1) : ''
}

Не писать комментарии нормально, логика кода проста, а имена переменных и функций полностью соответствуют логике кода.

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

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

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

Так что я думаю, что это утверждение следует понимать так: это не не писать комментарии, а не писать мусорные комментарии.

Что такое спам-комментарии? У Рори много нежелательных комментариев, которые не важны. Комментарии должны быть сосредоточены на том, «что сделано», а не на том, «как это сделать».

function objToUrlParam(obj = {}) {
    let param = ''
    for (let key in obj) {
        param += '&' + key + '=' + obj[key]
    }
    
    return param? '?' + param.substr(1) : ''
}

Например, в приведенной выше функции вы можете написать такой комментарий: «Преобразовать объект в параметр URL». Это также можно записать так: «Сначала пройдитесь по объекту, получите каждую пару ключ-значение, соедините их вместе и, наконец, добавьте знак вопроса впереди, чтобы превратить его в параметр URL».

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

Давайте взглянем на другой горячий глаз:

public class Program  
{  
    static void Main(string[] args)  
    {  
        /* 这个程序是用来在屏幕上  
         * 循环打印1百万次”I Rule!”  
         * 每次输出一行。循环计数  
         * 从0开始，每次加1。  
         * 当计数器等于1百万时，  
         * 循环就会停止运行*/  
 
        for (int i = 0; i < 1000000; i++)  
        {  
            Console.WriteLine(“I Rule!”);  
        }  
    }  
}

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

Как проверить спецификации кода

Спецификация сформулирована, так как же обеспечить ее строгое соблюдение? В настоящее время существует два метода:

1. Используйте инструмент для проверки формата кода.
2. Используйте проверку кода, чтобы просмотреть имена переменных и комментарии.

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

Давайте посмотрим, как использовать инструменты для проверки форматирования кода.

ESLint

ESLint изначально был проектом с открытым исходным кодом, созданным Николасом С. Закасом в июне 2013 года. Его цель — предоставить подключаемый модуль для обнаружения кода javascript.

1. Скачать зависимости

// eslint-config-airbnb-base 使用 airbnb 代码规范
npm i -D babel-eslint eslint eslint-config-airbnb-base eslint-plugin-import

2. настроить.eslintrcдокумент

{
    "parserOptions": {
        "ecmaVersion": 2019
    },
    "env": {
        "es6": true,
    },
    "parser": "babel-eslint",
    "extends": "airbnb-base",
}

3. существуетpackage.jsonизscriptsдобавить эту строку кода"lint": "eslint --ext .js test/ src/". затем выполнитьnpm run lintВы можете начать проверку кода. в кодеtest/ src/каталог кода, который нужно проверить, здесь указано, что нужно проверитьtest,srcкод в каталоге.

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

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

stylelint

stylelint — это инструмент с открытым исходным кодом для проверки форматирования кода CSS. Подробнее о том, как его использовать, см. в следующем разделе.

Автоматически форматировать код с помощью VSCode

Форматирование кода JavaScript

Установите VSCode, затем установите плагин ESLint.

выберитеFile -> Preference-> Settings(Если установлен пакет китайских плагинов, это должен быть Файл -> Параметры -> Настройки), найдите eslint и нажмитеEdit in setting.json.

Добавьте следующие параметры в файл конфигурации

    "editor.codeActionsOnSave": {
        "source.fixAll": true,
    },

После настройки VSCode будет основан на вашем текущем проекте..eslintrcДокументируйте правила для проверки и форматирования кода.

TypeScript

Скачать плагин

npm install --save-dev typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

существует.eslintrcФайл конфигурации, добавьте следующие два элемента конфигурации:

module.exports = {
    parser: '@typescript-eslint/parser',
    plugins: ['@typescript-eslint'],
}

в корневом каталогеpackage.jsonдокументscriptsДобавьте в опции следующие элементы конфигурации:

"scripts": {
  "lint": "eslint --ext .js,.ts,.tsx test/ src/",
},

test/ src/это каталог, который вы хотите проверить. После модификации теперь и ts-файл можно автоматически форматировать.

расширять

Как форматировать HTML и CSS в файлах HTML, Vue (или других суффиксах)?

Для этого необходимо использовать форматирование, поставляемое с VSCode, и сочетание клавишshift + alt + f. Предполагая, что текущий VSCode открывает файл Vue, нажмитеshift + alt + fВам будет предложено выбрать спецификацию форматирования. Если подсказки нет, уже есть спецификация форматирования по умолчанию (обычно плагин vetur), то весь код в файле Vue будет отформатирован, а правила форматирования можно настроить самостоятельно.

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

Поскольку правила форматирования ESlint были установлены ранее, файлу Vue нужно только форматировать код в HTML и CSS, и не нужно форматировать код JavaScript, поэтому нам нужно запретить vetur форматировать код JavaScript:

После завершения настройки в соответствии с приведенным выше рисунком вернитесь к файлу Vue прямо сейчас. Не стесняйтесь зашифровать формат кода и нажмитеshift + alt + f, вы обнаружите, что код в HTML и CSS отформатирован, а код в JavaScript — нет. Это не имеет значения, так как форматирование ESlint было задано, поэтому, пока выполняется операция сохранения, код JavaScript также будет автоматически отформатирован.

Точно так же можно форматировать и другие типы файлов.

Форматировать CSS-код

Скачать зависимости

npm install --save-dev stylelint stylelint-config-standard

Создайте новый в корневом каталоге проекта.stylelintrc.jsonфайл и введите следующее:

{
    "extends": "stylelint-config-standard"
}

VSCode добавитьstylelintПлагин:

Тогда вы сможете увидеть эффект.

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

{
    "extends": "stylelint-config-standard",
    "rules": {
        "indentation": 4
    }
}

Проверка кода Проверка кода

Ревью кода — это действие, при котором кто-то еще проверяет ваш код. Существуют различные способы рецензирования: например, парное программирование (один человек пишет, один человек читает) или все рецензируют друг друга в определенный момент времени (один или несколько человек).

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

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

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

git спецификация

Спецификация git обычно включает в себя два пункта: спецификацию управления ветвями и спецификацию git commit.

управление филиалом

Общий проект делится на основную ветку (мастер) и другие ветки.

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

Если вы хотите изменить серьезную ошибку, вы также можете открыть новую ветку из главной ветки и назвать ее номером ошибки.

# 新建分支并切换到新分支
git checkout -b test
# 切换回主分支，合并新分支
git checkout master
git merge test

Обратите внимание, что при слиянии новой ветки обратно в master, если в новой ветке есть неоднозначные коммиты, рекомендуется сначала слить их (используя git rebase). После слияния объедините новую ветку обратно с основной веткой.

спецификация коммита git

git должен заполнять сообщение коммита каждый раз, когда вы делаете коммит.

git commit -m 'this is a test'

На этот раз сообщение о коммите представляет собой краткое описание вашего кода.

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

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Мы можем найти, что сообщение Commit диск разделено на три части (используя пустую сегментацию):

1. Строка заголовка (тема): Обязательно, опишите тип и содержание основной модификации.
2. Содержание темы (тело): Опишите, почему была сделана модификация, какая модификация была сделана, а также идеи развития и т. д.
3. Нижний колонтитул: Вы можете писать комментарии и ставить ссылки на номера BUG.

type

Тип фиксации:

• подвиг: новые функции, новые функции
• исправить: исправить ошибку
• perf: изменения кода для повышения производительности
• рефакторинг: рефакторинг кода (рефакторинг, модификация кода без влияния на внутреннее поведение и функции кода)
• документы: Изменения в документации
• стиль: модификация формата кода, обратите внимание, что это не модификация css (например, модификация точки с запятой)
• test: добавлять и изменять тестовые случаи
• build: влияет на сборку проекта или модификацию зависимостей
• revert: вернуть последнюю фиксацию
• ci: изменение файла, связанное с непрерывной интеграцией
• рутинная работа: другие модификации (модификации, не относящиеся к вышеперечисленным типам)
• релиз: выпустить новую версию
• рабочий процесс: изменение файла, связанное с рабочим процессом

scope

Область функции или файла, затронутая сообщением фиксации, например: маршрут, компонент, утилиты, сборка...

subject

Обзор сообщений фиксации

body

Конкретное содержимое модификации может быть разделено на несколько строк.

footer

Некоторые замечания, обычно ссылка на КРИТИЧЕСКОЕ ИЗМЕНЕНИЕ или исправленную ошибку.

Пример

исправить (исправить ОШИБКУ)

Лучше всего добавлять описание области действия к каждому коммиту git.

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

// 示例1
fix(global):修复checkbox不能复选的问题
// 示例2 下面圆括号里的 common 为通用管理的名称
fix(common): 修复字体过小的BUG，将通用管理下所有页面的默认字体大小修改为 14px
// 示例3
fix(test): value.length -> values.length

подвиг (добавление новых функций или новых страниц)

feat: 添加网站主页静态页面

这是一个示例，假设对任务静态页面进行了一些描述。
 
这里是备注，可以是放 BUG 链接或者一些重要性的东西。

работа (другие модификации)

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

chore: 将表格中的查看详情改为详情

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

Проверить спецификацию фиксации git

использоватьgit hookВозможность запуска пользовательских сценариев при выполнении определенных важных действий.

Проверка спецификации git commit не является исключением, нам нужно передать gitpre-commitфункция крючка. Конечно, вам также нужно скачать вспомогательный плагин хаски, который поможет вам проверить.

Хук pre-commit запускается до ввода информации о коммите, он используется для проверки моментального снимка, который должен быть зафиксирован.

husky — это инструмент с открытым исходным кодом, с помощью которого мы можемpackage.jsonконфигурацияgit hookсценарий. Давайте посмотрим, как использовать:

скачать

npm i -D husky

существуетpackage.jsonДобавьте следующий код:

"husky": {
  "hooks": {
    "pre-commit": "npm run lint",
    "commit-msg": "node script/verify-commit.js",
    "pre-push": "npm test"
  }
}

Затем создайте новую папку в корневом каталоге вашего проекта.script, и создайте новый файл нижеverify-commit.js, введите следующий код:

const msgPath = process.env.HUSKY_GIT_PARAMS
const msg = require('fs')
.readFileSync(msgPath, 'utf-8')
.trim()

// 提前定义好 commit message 的格式，如果不符合格式就退出程序。
const commitRE = /^(feat|fix|docs|style|refactor|perf|test|workflow|build|ci|chore|release|workflow)(\(.+\))?: .{1,50}/

if (!commitRE.test(msg)) {
    console.error(`
        不合法的 commit 消息格式。
        请查看 git commit 提交规范：https://github.com/woai3c/Front-end-articles/blob/master/git%20commit%20style.md
    `)

    process.exit(1)
}

Теперь, чтобы объяснить значение каждого хука:

1. "pre-commit": "npm run lint",существуетgit commitперед казньюnpm run lintПроверьте формат кода.
2. "commit-msg": "node script/verify-commit.js",существуетgit commitВыполнить скрипт, когдаverify-commit.jsПодтвердите сообщение фиксации. Если он не соответствует формату, определенному в скрипте, будет сообщено об ошибке.
3. "pre-push": "npm test", после выполненияgit pushПеред отправкой кода в удаленный репозиторий выполнитеnpm testпровести тестирование. Если тест не пройден, отправка не будет выполнена.

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

Кроме того, я предоставляю простой инженерныйDEMO. Он включает в себя код автоматического форматирования и проверку git.Если вы все еще не знаете, как настроить после прочтения статьи, вы можете обратиться к ней.

Спецификация проекта

Спецификация проекта в основном относится к организации и именованию файлов проекта. Унифицированная спецификация проекта предназначена для облегчения управления и модификации, и не будет документов одного и того же характера, появляющихся в разных местах. Например, одна и та же картинка появляется вassetsКаталог, один появляетсяimgсодержание.

Чтобы создать каталог, его нужно разделить по назначению. Например, наиболее распространенными каталогами являются: Документация.doc,ресурсsrc,тестовое заданиеtest...

├─doc
├─src
├─test

srcКаталог ресурсов может быть дополнительно подразделен:

├─api
├─asset
├─component
├─style
├─router
├─store
├─util
└─view

Сейчас есть много способов называть файлы (аббревиатура или нет)img image, во множественном числеimg imgs, если имя файла слишком длинное, используйте верблюжий регистр или используйте - подключениеoneTwo one-two). По сути, неважно, какой метод используется, главное, чтобы метод именования был унифицирован.

Например, кто-то в команде, который называет каталог, любит использовать форму множественного числа (apis), некоторые люди любят использовать единственное число (api), это не допускается и должно быть унифицировано.

Спецификация пользовательского интерфейса

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

Способ выразить

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

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

Если спецификация этих представлений не установлена, могут возникнуть следующие ситуации:

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

Единое наименование

Унифицированное именование для снижения затрат на связь.

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

1. единая дата со временем
2. одно свидание без времени
3. диапазон дат со временем
4. диапазон дат без времени

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

Подводя итоги, мы можем обнаружить, что преимущества создания спецификаций UI два раза:

1. Единые стандарты пользовательского интерфейса страницы, экономящие время на разработку пользовательского интерфейса.
2. Сократите затраты на связь и повысьте эффективность фронтенд-разработки.

резюме

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

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

использованная литература

• husky
• stylelint
• eslint

Начало работы с фронтенд-инжинирингомПолнотекстовый каталог:

1. Выбор технологии: как сделать выбор технологии?
2. Единообразные нормы: как сформулировать нормы и использовать инструменты для обеспечения их строгого соблюдения?
3. Компонентизация интерфейса: что такое модульность и компонентизация?
4. Тестирование: как писать модульные тесты и E2E (сквозные) тесты?
5. Инструменты сборки: что такое инструменты сборки? Каковы особенности и преимущества?
6. Автоматическое развертывание: как использовать Jenkins, Github Actions для автоматизации развертывания проектов?
7. Интерфейсный мониторинг: объясните принцип внешнего мониторинга и как использовать sentry для мониторинга проекта.
8. Оптимизация производительности (1): как определить производительность веб-сайта? Каковы некоторые практические правила оптимизации производительности?
9. Оптимизация производительности (2): как определить производительность сайта? Каковы некоторые практические правила оптимизации производительности?
10. Рефакторинг: зачем делать рефакторинг? Какие существуют методы рефакторинга?
11. Микросервисы: что такое микросервисы? Как построить проект микросервиса?
12. Serverless: что такое Serverless и как использовать Serverless?