Alan Notes

代码风格浅谈

·13 分钟阅读·#代码风格扫码分享文章

前端的代码风格规范主要还是 JavaScript 的风格规范 (JavaScript Style Guide)。JavaScript 比较出名的风格规范主要有 standard、 airbnb 、google等等。我们可以借助一些工具比如

目录
  1. 风格规范
  2. 编辑器相关
  3. 文件结构相关
    1. Yarn
    2. 组件化
    3. 前端框架
    4. 命名
  4. 代码风格相关
    1. HTML
    2. CSS / Stylus / Scss
    3. JavaScript
    4. Vue
    5. React
    6. Node
    7. 关于注释
  5. Github 相关
  6. 总结

风格规范#

前端的代码风格规范主要还是 JavaScript 的风格规范 (JavaScript Style Guide)。JavaScript 比较出名的风格规范主要有 standard、 airbnb 、google等等。我们可以借助一些工具比如 ESLint、 TSLint、Prettier 来规范或者美化代码，在编辑器上也可以自定义风格规范来格式化代码，使得代码格式统一美观。

其实，代码看多了（指源码）、写多了，自然而然就能形成自己的代码风格。在团队中，制定一套符合自己团队的开发规范，对于团队的开发工作至关重要。

下面谈谈一些自己的代码风格，不仅仅是 JavaScript，什么都可以聊一下。

【最新更新 2020/05/26】

编辑器后面一直在使用 VSCode，前端现在使用 Prettier 2.0 的默认配置（也是 Deno 的 fmt 风格）。最近也开始浅浅的学习了多门后端语言，已经不再纠结之前的单引号去分号的代码风格，感觉符合语言规范、一致性就好。另外建议文件名还是使用小写字母单词，词组名称使用连号或者下划线连接小写字母单词，不要使用大写字母单词。

编辑器相关#

之前一直在使用 JetBrain 公司的 WebStorm 编辑器，但是在今年已经全面改用了微软的 VSCode 编辑器，现在也在慢慢已经习惯并依赖上了 VSCode ，对 VSCode 也越来越熟悉。

在特推上的一些大神展示的代码很多都是用 VSCode 的，然后国内的掘金、知乎社区上也越来越多人在讨论 VSCode，我也开始尝试者使用 VSCode。

用 VSCode 的一开始是写博客内容或者一些笔记，博客文章使用的是 markdown 格式，VSCode 天生就对 Markdown 支持非常好，特别是比 WebStorm 的预览效果好多了。WebStorm 一开始对 Markdown 的预览还好，后面不知道怎么搞的，预览的页面不清晰，非常模糊。

这时候写代码还是用 WebStorm，毕竟它的智能补全很好用，直到后面发现 VSCode 的插件系统是如此强大，好多插件完全可以替代 WebStorm 的功能，而且定制化更强，也有很多非常漂亮的主题，后面就逐渐改用 VSCode，然后再也离不开它了。比如CodeRunner插件可以直接运行各种语言的代码，非常方便。小程序插件minapp，让我写小程序更好方便，这在 WebStorm 上是无法实现的。

前端代码格式化插件Prettier，美化我的前端代码文件比如Html、CSS、JavaScrip，甚至是 Vue 文件和 或者 Markdown 文件。虽然 WebStorm 也可以实现相同的功能，但是需要你去详细的配置。VSCode 一个插件就搞定了。之后，我的项目基本上都是采用Prettier美化代码。

一些非常美观的主题，图标，还有自定义的字体，都让我爱不释手。其他的功能插件比如同步配置Setting sync和 LeetCode 插件，更是让我离不开它。

VSCode 不仅有强大的插件系统，还自带调试功能，可以轻松调试代码。另外最重要的一点，VSCode 是开源的、完全免费的软件，再也不用去隔三岔五的去找 WebStorm 的服务许可。而且 VSCode 是微软主推的 Github 明星项目，全世界的开发者去更新和维护它，以后只会越来越好。

有的团队要求统一使用编辑器，相信 VSCode 会是个很好的选择。

文件结构相关#

Yarn#

前端项目的工程化离不开 Node.js，它自带的包管理工具 NPM，但是感觉并不好用。我一般会使用脸书出品的 Yarn 工具来管理包。Yarn 的安装包的速度也比 NPM 快，而且提示信息更友好，也更安全。

组件化#

现在前端的三大框架 Vue、React、Angular 提倡经常组件化开发，把页面切分成一个个组件，提高开发效率和可维护性。对于组件，我有自己的风格。

比如组件的命名，我比较喜欢 React 对于组件规定，组件的名字必须采用大写的驼峰形式，在页面引入组件时，也采用大写的驼峰的标签名，这样可以明确的和一般标签区分开来，可读性更高。后面当你看到大写的驼峰名字时，就知道这是一个组件，这样可以更好的查找组件。

如果组件是以文件夹来区分，文件夹名称和组件的名称最好写成一样的，这样单独打开组件文件时，就可以清楚的知道这是一个什么组件，然后额外创建一个索引文件index.js，来导出组件文件，这样的话，再引用这个组件的时候就不要写两次名称了（文件夹名称和组件名称）。

React 的组件就是 JSX，它和样式一般是分离的，除非你使用“styled-jsx”，把样式写在 JSX 里面，所以最好采用文件夹的形式来区别不同的组件。

而 Vue 有独立的.vue格式的文件，可以把结构、样式、交互的代码都写在一起，实现高内聚，所以以文件的形式来区分就可以了。如果组件中需要引入本地图片，可以把图片和组件放在同一个文件夹中，这时以文件夹的形式来区分会比较好。当然也可以把所有的本地图片统一放在一个文件夹中去管理，这样其实也不错。

前端框架#

使用@vue/cli脚手架生产的文件目录中，默认是使用 views 目录来存储页面组件的， 而 components 目录存储 一般组件的，还有 assets 存储其他的比如全局样式文件或者辅助函数文件。我觉得这样的文件结构非常清晰，值得借鉴。

在状态管理方面，Vue 的状态是集中在 store 的文件夹中统一管理的，因为它的状态管理库 Vuex 是高度集成和封装的，放在一起统一管理很方便，如果状态比较复杂，还可以使用模块来分割不同的状态。

而 React 的状态管理却不一样，因为 Redux 风格的代码写起来非常啰嗦，如果都集中到一个文件夹去管理，这个文件夹里面的文件会非常多，然后每个文件的代码也会很多。这时候，可以根据功能或者页面的不同，把状态文件放在每个页面下面去管理可，这样可能会更好一些。

命名#

一个好的命名不仅可以很好的诠释代码的作用，还能让人耳目一新。

文件命名

组件文件或者组件所在的文件夹建议采用大驼峰类型来命名，而其他的文件则采用小写字母或者小写字母加连字符来命名，如Home.vue、request-api.js。

当然，也可以统一采用小写字母或者小写字母加连字符来命名所有的文件，如home.vue、request-api.js。但是组件在代码中的引用还是建议使用大驼峰的类型，这样可以更好的和普通的标签区分开来。

变量命名

代码中变量的命名，JavaScript 规范一般是推荐是使用小驼峰命名方式。

const newObj = {};
function test1() {}

但是，命名类或者构造函数时需要使用大驼峰命名方式。

function Person(name, age) {
  this.name = name;
  this.age = age;
}
 
class Person {
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }
}

然后，对于一些常量或者状态类型可以使用大写字母加下划线的命名方式。

const MAX_HEIGHT = 300;
export const SET_SINGER = "SET_SINGER";

代码风格相关#

我的前端项目一般是通过 ESLint 和 Prettier 来规范代码风格的。在 VSCode 中需要下载 2 个插件, 插件名字是“ESLint” 和“Prettier - Code formatter”，这两个都是非常流行的插件，下载量都达到百万以上。

HTML#

采用 Prettier 推荐的的风格。在标签属性很多时导致标签超过一定的长度时，会把标签的属性分行。如果属性较多但标签长度不长时不分行。这样就可以在节约空间和可读性中之间达到一个平衡。长度是由 Prettier 来定义的，这个长度是比较合理的。

<!-- 属性太多导致标签太长属性分行 -->
<transition
  name="normal"
  @enter="enter"
  @after-enter="afterEnter"
  @leave="leave"
  @after-leave="afterLeave"
>
  <!-- other tag -->
  <!-- 属性比较多但是标签不长不分行 -->
  <img width="100%" height="100%" :src="currentSong.image/>
</transition>

CSS / Stylus / Scss#

现在直接写 CSS 的代码比较少，一般都写 Stylus 或者 Scss 代码。

Stylus 是 Node 社区推出的 CSS 预处理器，语法灵活简单。另外，在格式上也可以设置两种不同的风格：

  • 极简风格，没有大括号，没有分号，甚至在属性名和属性之间也没有冒号，只用空格隔开。
  • 正常风格，和极简风格完全相反，有大括号、分号和冒号。这种风格有点类似于 Scss，如果你使用这种格式，再加上 Scss 的关键字，就可以转换成 Scss 文件。

当然你也可以自定义格式，我喜欢取两者之间的设置，保留了冒号，但是去掉了分号和大括号，这样可读性更好，也很节省空间。

因为我现在主要使用 VSCode 编辑器，安装了“Manta's Stylus Supremacy”插件，这样插件可以设置 Stylus 的格式，不但可以设置一般的 Stylus 文件，还可以设置 Vue 文件中的 Stylus 代码的风格，只需要在 Vue 的插件 Vetur 中设置 Stylus 的格式化工具为“stylus-supremacy”即可。

下面是我的 Stylus 配置

{
  "stylusSupremacy.insertBraces": false, // 去大括号，默认是 true
  "stylusSupremacy.insertSemicolons": false, // 去分号，默认是 true
  "stylusSupremacy.insertColons": false // 去冒号，默认是 true，如果不去冒号，删掉这条设置即可
}

Sass 在第三个版本时改名 Scss，全面兼容原生的 CSS 代码，它是目前最流行、最多人使用的 CSS 预处理器，功能非常强大激进，编辑器的支持也很好，很多流行的 UI 库编写 CSS 代码时也使用它。Sass 的底层一开始是使用 Ruby 语言编写的，所以使用它时需要安装 Ruby 语言环境，后面别的社区也使用了其他语言来实现它，其中 Node 社区对应的库的名称是node-sass，不过这个库不好安装，经常会安装失败，后面社区又使用dart语言来实现它，这个库的名称是dart-sass，这是源码库，使用这个库编译后的sass很好安装，而且 Webpack 中编译的 Loader：sass-loader也可以依赖这个库，终于不用再安装node-sass了。

Scss 在 VScode 编辑器中支持非常好，可以直接使用 Prettier 插件来格式化代码，另外在 Vue 文件中的支持也比 Stylus 更好，可以显示代码中设置的各种颜色。React 官方脚手架只支持这个 CSS 预处理。非常推荐使用这个预处理器，现在编写 CSS 也主要使用这个它。

npm install sass  # 安装 dart-sass 编译好的 sass 库

JavaScript#

还是采用 Prettier 推荐的风格，Prettier 真是个神器。不过我一般会添加两个自定义设置，可以在 VSCode 的配置文件中添加下面的配置:

{
  "prettier.semi": false,
  "prettier.singleQuote": true
}

如果你的项目中使用 ESLint 检查代码风格，你需要新建一个文件.prettierrc定制代码风格

{
  "semi": false,
  "singleQuote": true
}

这两个设置的作用分别是去掉分号和使用单引用。

其实 JavaScript 不加分号是完全没问题的，编辑器和插件会帮我们自动处理。比如在每行开头使用了方括号[]或者圆括号()，使用 Prettier 插件格式化代码，编辑器会自动在它们前面加上分号;。

使用单引号而不是双引号是因为在 JavaScript 中单引号和双引号并没有本质区别。使用单引号可以不用去按shift，一定程度上减少了工作量。

如果你想要在 Vue 文件中的 JavaScript 部分也使用这样的风格的化，可以在 VSCode 的配置文件中添加下面代码，在配置之前需要先安装“vetur”插件

{
  "vetur.format.defaultFormatterOptions": {
    "prettier": {
      "semi": false,
      "singleQuote": true
    }
  }
}

Vue#

Vue 是我最熟悉的前端框架，一般在使用官方脚手架创建项目时，我会选项 ESLint 和 Prettier 来规范和美化代码，然后再重新定制下 Prettier，即不使用分号和使用单引号。

React#

如果是你自己搭建 React 环境，也可以使用 ESLint 和 Prettier 来规范和美化代码。

如果使用官方的脚手架“create-react-app”创建的项目，它统一采用的react-app风格的 ESLint 规范和美化代码，这个风格是非常宽松的，对于 Prettier 风格的代码不会排斥。如果你的 VSCode 编辑器已经安装 Prettier 插件 ，就可以用来格式化 React 代码。当然，你也可以添加 Prettier 规范到 ESLint 配置中。

Node#

使用 Node 可以为前端文件配置后端的服务器时，我一般会把 Node 的文件放在前端项目中，这样 Node 的文件也能先享用前端设置的格式风格规范代码。

如果使用一些手脚架工具搭建项目的，大部分脚手架也是使用 ESLint 和 Prettier 来规范和美化代码，然后再定制一下自己的风格即可。

如果是自己搭建的 Node 项目，可以手动配置 ESLint 和 Prettier ，配置方法如下。

首先，安装依赖

yarn add eslint eslint-config-prettier eslint-plugin-prettier -D

然后，编辑配置文件.eslintrc

{
  "root": true,
  "parserOptions": {
    "ecmaVersion": 2018,
    "sourceType": "module"
  },
  "env": {
    "node": true
  },
  "extends": ["plugin:prettier/recommended"],
  "rules": {
    // other rules
  }
}

最后，定制个人风格，创建并编辑配置文件.prettierrc

{
  "semi": false,
  "singleQuote": true
}

关于注释#

JavaScript 的注释主要有两种，单行的注释//和多行注释/* */。

一般我喜欢使用单行的注释//，占用空间比较小，并且会把注释写在代码的右边，只有代码很长才会写在代码的上一行。多行注释/* */一般用于注释函数、类、各种语句等代码块，特别是注释函数的参数和返回值非常方便。不过我还是喜欢用单行注释，因为多行注释太占用空间了，除非需要特别注释参数。

另外，单行注释//也可以注释函数等代码块或者多行代码，只需要多写几行//就可以了，即使这样也比/* */更节省空间。

为了可读性更强，英文单词和汉字之间用空格隔开，数字和汉字之间用空格隔开，在 Markdown 中使用prettier插件可以很好美化我们编写的内容，这个插件会帮我们分隔开。但是，在代码文件的注释中，就只能靠我们自己去分隔了。

Github 相关#

Git 是代码版本控制软件，Github 是著名的代码托管平台，这个平台所使用的就是 Git 控制软件版本的。

现在学编程的同学或者已经有工作的程序员，基本上都会在 GitHub 或者其他类似的平台上注册账号，建立自己的代码托管仓库，分享自己的代码或者和他人进行交流和学习。

我们每次为自己的仓库提交或者更新代码的时候，都会提交一条 Commit Message，用来记录我们提交的信息，之以后就可以很好的查询这些信息了。

如果是个人的项目的仓库提交代码信息时，按照自己想法提交信息即可，比如提交 update、第一次提交等信息。像怎么写就怎么写，这都没有关系。但是如果想把项目做好点，就不能这样随便提交信息，应该要规范一点。

怎么规范呢？借助工具来规定提交的信息的格式和内容，使得提交的信息更加规范，可读性更强。可能每个公司或者团队都有一套自己的规范，这里我介绍下我自己的规范，我使用的是 Angular 团队的规范，需要使用第三方库来规范提交的信息。下面是使用的步骤。

首先，安装依赖

yarn add commitizen cz-conventional-changelog

配置文件，在package.json中：

"script": {
    ...,
    "commit": "git-cz",
},
"config": {
    "commitizen": {
      "path": "node_modules/cz-conventional-changelog"
    }
  }

然后当你提交 commit 的时候，输入命令后，会出现下面的提示界面

yarn commit

上面的类型分别由以下的类型组成：

  • feat: 新特性
  • fix: 修改问题
  • docs: 文档相关
  • style: 代码风格相关
  • refactor: 代码重构
  • pref: 性能优化相关
  • test: 测试相关
  • build: 构建相关
  • ci: CI 相关
  • chore: 其他修改, 不包括 src 和 test
  • revert: 版本回溯相关

此时你通过上下方向键选择对应的类型，然后根据提示输入内容，比如你选择的是“feat”，之后在“short message” 选项时填写“add article”信息，其他的可不填，这样生成的 Commit Message 内容就是“feat: add article”。

这条信息说明增加了一个功能：添加了一篇文章。

你也可以在全局安装依赖，这个就不用为每个项目都安装这些依赖和配置文件。

yarn global add  commitizen cz-conventional-changelog # 全局安装

然后在用户的根目录下面，创建配置文件.czrc，编写下面的代码

{ "path": "cz-conventional-changelog" }

之后再任何一个项目文件中，你提交了文件到暂存区后，需要提交修改时，只需要在命令行中输入

git cz

就会跳出和上面yarn commit一样的提示界面，然后根据提示信息输入相关内容即可。其实如果搭配 Git Hook，效果会更好。在我们每次提交信息之前都会检测代码格式是否符合规范，只有符合规范，才能正常提交代码。

首先，安装相关依赖

yarn add @commitlint/cli @commitlint/config-conventional lint-staged -D

配置文件，在package.json中:

"script": {
  "precommit": "lint-staged"
},
 
"lint-staged": {
  "**/*.JavaScript": [
    "prettier --write",
    "git add"
  ]
},
 
"commitlint": {
  "extends": [
    "@commitlint/config-conventional"
  ]
},

运行yarn commit命令时，会先触发 precommit 的脚本，然后执行lint-staged命令，检测所有的 JavaScript 文件是否符合我们设置的规范，如果不符合规范，有先尝试使用prettier --write来修复一些简单的格式问题，如果修复成功，会重新进行提交，如果修复不成功，而不会提交代码，并且提示出现问题，需要我们手动修复之后再进行提交。

总结#

代码风格是我们在写代码的过程中慢慢形成的，好的代码风格对于我们有非常重要的影响。好的代码风格不仅增强可读性和提高代码可维护性，还能体现一个人的编程素养。