代码开发规范

作者: 林思念 | 来源:发表于2022-09-04 00:40 被阅读0次

代码规范
代码开发规范
开发代码规范
代码开发规范
PM篇
HTML：网站通用代码规范
iOS开发总结之代码规范
前端开发规范
IntelliJ IDEA安装 Alibaba Java Cod
中型App开发框架总结

背景
随着项⽬复杂度提⾼、团队成员增多，但编码的⻛格不统⼀，会增加后期维护代码的成本以及编码效率。如果制定⼀套好的规范，可以解决很多意外的bug、可以规范⾃⼰的编码习惯、可以让 code Review 更加简单。

⽬标

降低维护代码的成本、提高多⼈协作的效率
遵守最佳实践，确保写出更⾼效且优雅的代码

Git提交信息规范

在使⽤ Git 进⾏代码的分布式版本控制时，规范化 commit message 可以帮助开发人员在多⼈开发协作中更好的理解他⼈对代码的改动信息，避免⼤家按照各⾃的理解和习惯（甚⾄是随意）书写，⽽对他⼈和⾃⼰造成困惑，从⽽增加代码审查和纠错的时间成本。

本规范基于 Conventional 规范，这是标准的 commit message 的写法，⽐较合理和系统化，并且可以搭配⼯具校验。

作⽤

⼀个规范化的 commit message ，具有以下作⽤：

• 提供更多的历史信息，⽅便快速浏览

• 可以过滤某些 commit （⽐如⽂档改动），便于快速查找信息

• 可以直接从 commit ⽣成 CHANGELOG.md

格式

使⽤ git commit 可以提交多⾏，完整的格式包括三个部分：

• Header【必填】

• Body【选填】

• Footer【选填】

<type>(<scope>): <subject> <!-- header -->
 <!-- 空⼀⾏ -->
<body>
 <!-- 空⼀⾏ -->
<footer>

任意⼀⾏都不应该超过100字符，这样的信息在 github 和各种各样的 git ⼯具上能有更好的可读性。

Header 是必填，Body 和 Footer 是选填，因此这里只介绍Header的写法

Header 包括三个字段：

• type（必填）

• scope（选填）

• subject（必填）

<type>(<scope>): <subject>

Type

⽤于说明 commit 的类别，只允许使⽤下⾯ 7 个标识：

• feat：新功能（feature）

• fix：修补bug

• docs：⽂档（documentation）

• style：格式（不影响代码运⾏的变动）

• refactor：重构（即不是新增功能，也不是修改bug的代码变动）

• test：增加测试

• chore：构建过程或辅助⼯具的变动

Scope

⽤于说明 commit 影响的范围，⽐如数据层、控制层、视图层等等

Subject

⽤于对 commit ⽬的的简短描述，不超过50个字符

以动词开头，使⽤第⼀⼈称现在时，⽐如 change ，⽽不是 changed 或 changes 第⼀个字⺟⼩写
注意：结尾不需要加句号（.）

# ⽰例⼀
 fix(login): 修改登录账号加密⽅式

# ⽰例⼆
 fix: 去除登录⻚⾯console代码

配合⼯具

使⽤⼯具 commitozen 来辅助格式化 git commit message ，它提供了⼀种问询式的⽅式去获取所需信息
https://www.npmjs.com/package/commitizen
• Git提交信息钩⼦：husky
https://typicode.github.io/husky/#/?id=install
提交信息自动验证⼯具: @commitline/cli
https://commitlint.js.org/#/
使用如下代码后，便自动生成校验钩子，在代码提交前校验提交信息规范，对于格式不对的会阻止提交

# Install Husky v6
 npm install husky --save-dev
# or
 yarn add husky --dev

# Active hooks
 npx husky install
# or
 yarn husky install

 # Install and configure if needed
    npm install --save-dev commitizen @commitlint/{cli,config-conventional}
# For Windows:
    npm install --save-dev commitizen @commitlint/config-conventional @commitlint/cli

# Configure commitlint to use conventional config
    echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
 
# Add hook
 npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'
# or
 yarn husky add .husky/commit-msg 'yarn commitlint --edit $1'

编码规范
ESLint 是⼀个按照规则给出报告的代码检测⼯具，使⽤它可以避免低级错误和统⼀代码⻛格，这对公司团队开发⾮常实⽤。

以React / Vue3 Cli项⽬中配置ESLint为例，⼤概说明下基本配置以及作⽤

// 需要安装 babel-eslint 
// babel-eslint 将不能被常规linter解析的代码转换为能被常规解析的代码
npm install --save-dev eslint babel-eslint

// 进⾏初始化，如果选择airbnb，会⾃动安装部分相关的插件
eslint --init

// 进⾏初始化后，会在项⽬根⽬录下⽣成⼀个 .eslintrc.js ⽂件

React 版本安装完后会 package.json 一般会添加如下⼏个依赖包

  "eslint": "^7.29.0",
  "babel-eslint": "^10.1.0",  
  "eslint-config-airbnb/react-app": "^18.2.1", 
    // 使用create-react-app创建的 默认将使用 eslint-config-react-app
  "eslint-plugin-import": "^2.23.4",
  "eslint-plugin-jsx-a11y": "^6.4.1",
  "eslint-plugin-react": "^7.24.0",
  "eslint-plugin-react-hooks": "^4.2.0",

Vue 版本由于是通过vue-cli创建的，所以会额外增加 @vue/cli-plugin-eslint

"eslint": "^7.29.0",
"babel-eslint": "^10.1.0", 
@vue/cli-plugin-eslint
eslint-plugin-vue

通过 eslint --init 后会自动生成 .eslintrc.js

React

module.exports = {
  root: true,
  env: {
    browser: true,
    es6: true,
    node: true,
  },
  extends: ["react-app"],
  globals: {},
  parserOptions: {
    ecmaVersion: 2018,
    sourceType: "module",
    parser: "babel-eslint",
  },
  plugins: [],
  rules: {
    eqeqeq: 1,
    "no-unused-vars": 1,
    "no-var": 2,
    "no-debugger": process.env.NODE_ENV === "production" ? 2 : 1,
  },
};

Vue

module.exports = {
  root: true,
  env: {
    browser: true,
    es6: true,
    node: true
  },
  extends: ['plugin:vue/vue3-essential', 'eslint:recommended'],
  globals: {
    PhotoSwipe: 'readonly',
    PhotoSwipeUI_Default: 'readonly'
  },
  parserOptions: {
    ecmaVersion: 2018,
    sourceType: 'module',
    parser: 'babel-eslint'
  },
  plugins: ['vue'],
  rules: {
    eqeqeq: 1,
    'no-unused-vars': 1,
    'no-var': 2,
    'no-debugger': process.env.NODE_ENV === 'production' ? 2 : 1
  }
}

可以看到两个项目使用的rules规则相同，只是针对不同语法糖的格式校验，由于本身项目是通过cli项目创建的，所以使用cli默认封装的lint插件会更合适。

配合 husky 校验

在 package.json ⽂件中加⼊以下代码

 "scripts": {
    "lint": "echo 'eslint 检查开始...'  && eslint ./src --ext  .js .vue --fix"
 }

命令⾏⼯具, 在根⽬录下⼿动执⾏ npm run lint , 即会检测代码

使⽤ pre-commit git hook

pre-commit Hook是在Git提交之前⽤来⾃动检查待提交代码是否有错误的⼯具。

使⽤以下命令添加相关钩⼦

npx husky add .husky/pre-commit "npm run lint"

这样就可以对指定目录下的文件进行lint校验

添加 Prettier 统⼀格式化代码⻛格
Prettier的中⽂意思是“漂亮的、机灵的”，也是⼀个流⾏的代码格式化⼯具的名称，它能够解析代码，使⽤你⾃⼰设定的规则来重新打印出格式规范的代码。eslint 和 prettier 可以配合使⽤，也可以单独使⽤。下⾯我们主要讲eslint和prettier结合使⽤

ESLint 已经有了代码格式化的功能，为什么还需要使⽤Prettier呢？
各种 Linters 是按照规则(Rules)去检查代码的，遇到不符合规则的代码就会提⽰你，有的规则还能⾃动帮你解决冲突。

这些规则分为两类：

• Formatting rules

例如 ESlint 的 max-len 规则，设置单⾏⻓度不能超过 80 字符。ESLint会提⽰你去修复。⽽ Prettier 则不会这么⿇烦，它根本不管你之前符不符合什么规则，都先把你的代码解析成 AST，然后按照它⾃⼰的⻛格给你重新输出代码。

换句话说，Prettier 对应的是各种 Linters 的 Formatting rules 这⼀类规则，并且更加丰富和完善。⽽且你⽤了 Prettier 之后，就不会再违反这类规则了！不需要你⾃⼰⼿动修改代码。

• Code-quality rules

例如 ESLint 的no-unused-vars规则，不允许没⽤的变量定义出现。这种错误只能⽤⼾⾃⼰去⼿动修复。Prettier 对这类规则束⼿⽆策。⽽且这类规则也正是各种 Linters 的重点，因为它们真的能帮你发现很多低级的 Bug。

那么既要让 Prettier 帮你格式化代码，还想让 Linters 帮你挑出潜在的 Code-quality 类错误，怎么办？就需要 Prettier 和 Linters 配合使⽤。

Prettier 和 Linters 的整合需要做的两件事

禁⽤ Linters ⾃⼰的 Formatting rules，让 Prettier 接管这些职责。
让 Linters 执⾏时⾸先调⽤ Prettier 格式化，然后再检查 Code-quality 类规则。这是由 Linters 的 Plugin 实现的。

Prettier配置

npm i --D --save-exact prettier

npm i -D eslint-plugin-prettier eslint-config-prettier


// vue 需要额外安装
npm i -D @vue/eslint-config-prettier

prettier 代码格式化核⼼
eslint-plugin-prettier 插件，可以让eslint使⽤prettier规则进⾏检查，并使⽤ --fix 选项。像之前的格式不对时，eslint提⽰的红线。
eslint-config-prettier 插件，之前说了 eslint 也会检查代码的格式，这个插件就是关闭eslint 所有不必要或可能跟prettier产⽣冲突的规则。让prettier接⼿代码的格式校验

结合.eslintrc.js配置

// vue 中
extends: [... '@vue/prettier'],

 
 // React 
  
extends: [...  "plugin:prettier/recommended"],  
  
  
 以上配置做如下三件事：

  1. 使eslint-plugin-prettier⽣效
  2. 不符合prettier/prettier的规则，会报错。就是代码中提⽰的红线。
  3. 使eslint-config-prettier⽣效。就是会覆盖eslint中与prettier冲突的配置。

配置.prettierrc.json

{
    "tabWidth": 2,   // tab占⽤的字符数
    "trailingComma": "none", // 最后⼀个对象元素加逗号
    "semi": false, // 是否句末加分号
    "singleQuote": true,   // 是否⽤单引号
    "bracketSpacing": true // 是否对象，数组加空格
}

使⽤ lint-staged 只校验暂存区⽂件

lint-staged 是⼀个在git暂存⽂件上运⾏linters的⼯具，如果不使⽤这个⼯具的话，不管修改了⼏个⽂件在提交的时候会给所有⽂件执⾏⼀次lint检查，这样对于庞⼤的项⽬来说会浪费⼤量的校验时间。

npx mrm lint-staged

使⽤以上命令它将根据 package.json 依赖项中的代码质量⼯具来⾃动安装和配置husky和 lint-staged 。

⾃动在husky⽂件下创建 pre-commit ⽂件：

  #!/bin/sh
  . "$(dirname "$0")/_/husky.sh"

  npx lint-staged

⾃动在package.json⽂件中添加如下配置：

"lint-staged": {
     "*.js": "eslint --cache --fix"
}

有了以上基础配置后，在commit的时候就只对修改的⽂件进⾏lint和修复。但上面lint-staged配置还不够，因此可以扩展如下：

 "lint-staged": {   // lint-staged 配置
      "*.{js,jsx,md,vue}": [
         "prettier --write",
         "eslint --cache --fix",
         "git add"
      ]
}

这⾥ lint-staged 的配置是：
在 git 的待提交的⽂件中，在所有⽬录下的符合的文件都要执⾏三条命令。

• 第⼀条命令 prettier --write

◦ --write ：默认prettier是直接标准输出到终端的，这个配置代表直接格式化改写⽂件。

◦ 关于prettier的还有⼀些配置参考这⾥ prettier 配置文档
https://prettier.io/docs/en/options.html

• 第三条命令，将处理过的代码重新 add 到 git 中。

最终在使⽤Git提交代码的时候，会⾃动检测暂存区里的代码文件并进⾏格式化，如果有lint错误(error)会终⽌当前的commit push
添加 .editorconfig ⽂件覆盖编辑器⻛格

配置⼀个 .editorconfig ⽂件，在其中设置好要遵守的代码规范，放在项⽬的根⽬录下，就能够在⼏乎所有的主流 IDE 和编辑器中复⽤了，并将 .editorconfig ⽂件也提交到版本控制系统中，这样就不需要针对不同 IDE 和编辑器再单独进⾏设置了。

 // 表⽰是最顶层的配置⽂件，发现设为true时，才会停⽌查找.editorconfig⽂件
  root = true

  // * 表⽰所有的⽂件
  [*]
  //  对于所有的⽂件 始终在⽂件末尾插⼊⼀个新⾏
  insert_final_newline = true
  // 对于所有的⽂件，设置⽂件字符集为utf-8
  charset = utf-8
  // 设为true表⽰会去除换⾏⾏⾸的任意空⽩字符
  trim_trailing_whitespace = true
  // ⾏尾⽂件格式（Unix、DOS、Mac），值为lf、cr和crlf
  end_of_line = lf

  // 对于特定⽂件
  [*.{js,json,ts,tsx,vue}]
  // 设置缩进⻛格(tab是硬缩进，space为软缩进)
  indent_style = space
  // ⽤⼀个整数定义的列数来设置缩进的宽度
  indent_size = 2
  // 使⽤空格替代tab，并且⼀个tab会被替换为2个空格。

编辑器扩展(VSCode)

• 代码⻛格检查扩展： ESlint ；

• 代码⻛格格式化扩展： Prettier ；

• 编辑器设置扩展： EditorConfig for VS Code ；

关于 VScode 相关校验插件参考
https://juejin.cn/post/6844904099092119565

参考文档
1、Git提交信息规范
https://github.com/lingz1/standard/blob/master/code-repository/git-commit-message.md
2、ESlint 官方配置文档
https://eslint.org/docs/user-guide/configuring/
3、ESlint 中文文档
https://cn.eslint.org/docs/user-guide/configuring
4、EditorCOnfig 配置属性介绍
https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties
5、ESlint + prettier 配置及介绍
https://www.cnblogs.com/qiqi715/p/10247598.html
6、Lint _ stagged 使用教程
https://www.cnblogs.com/jiaoshou/p/12250278.html
7、vue+ vetur+eslint + prettier 自动格式化功能
https://juejin.cn/post/6844904099092119565
8、写React Hooks 前必读
https://zhuanlan.zhihu.com/p/113216415

代码规范
代码规范 1. 概述欢迎使用代码规范，这个是我借鉴京东前端代码规范，组织的内部规范。旨在增强团队开发协作、提高...
代码开发规范
1. 代码格式左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格反例： if (空格 a ==...
开发代码规范
开发代码规范子组件使用PureComponent进行继承（我也不知道为什么）子组件要用fragment标签进行...
代码开发规范
背景随着项⽬复杂度提⾼、团队成员增多，但编码的⻛格不统⼀，会增加后期维护代码的成本以及编码效率。如果制定⼀套好的规...
PM篇
PM 技术篇1.开发规范命名规范，异常处理规范，日志规范，统一框架，代码commit规范，代码评审规范，统一API...
HTML：网站通用代码规范
1. 概述常用代码规范旨在增强团队开发协作、提高代码质量和打造开发基石的编码规范，以下规范是团队基本约定的内容...
iOS开发总结之代码规范
iOS开发总结之代码规范
前端开发规范
前端代码规范 Front Standard Guide 前端 JS 项目开发规范规范的目的是为了编写高质量的代码...
IntelliJ IDEA安装 Alibaba Java Cod
写出优雅规范的代码应该是开发者的目标，在代码规范这方面我们熟知的阿里巴巴有一套自己的Java代码开发规范，个人觉得...
中型App开发框架总结
开发流程总图代码开发阶段 GitLab：代码管理服务。git分支规范 MockServer：前端/后台同步开发...

代码开发规范

配合 husky 校验

相关文章

代码规范

代码开发规范

开发代码规范

代码开发规范

PM篇

HTML：网站通用代码规范

iOS开发总结之代码规范

前端开发规范

IntelliJ IDEA安装 Alibaba Java Cod

中型App开发框架总结

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读