对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的字里行间流淌的是软件系统的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。——引用自《阿里规约》

一、命名规范

分类

  1. camelCase （驼峰式，也叫小驼峰命名， e.g. userInfo ）
  2. PascalCase （帕斯卡命名式，也叫大驼峰命名， e.g. UserInfo ）
  3. kebab-case （短横线连接式， e.g. user-info ）
  4. snake_case （下划线连接式， e.g. user_info ）

项目命名

  1. 全部采用小写方式， 以中划线分隔。
  2. 正确示例：lvji-web-pc
  3. 错误示例：lvji_web_pc / LvjiWebPc

目录命名

全部采用小写方式， 以中划线分隔，有复数结构时，要采用复数命名法， 缩写不用复数

正确示例 错误示例 说明
components Components 业务通用组件
images Images 图片库
utils Utils 工具库
demo-styles Demo_styles 示例样式
demo-scripts Demo_scripts 示例脚本

【特殊】组件目录使用 PascalCase ，其他目录统一使用 kebab-case 风格

  1. 正确示例： head-search / page-loading / authorized / notice-icon
  2. 错误示例： HeadSearch / PageLoading

JS、CSS、SCSS、HTML、PNG 文件命名

全部采用小写方式， 以中划线分隔

  1. 正确示例： render-dom.js / signup.css / index.html / company-logo.png
  2. 错误示例： renderDom.js / UserManagement.html

命名严谨性

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用

  1. 正确示例：henan / luoyang / rmb 等国际通用的名称，可视同英文。
  2. 错误示例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 年龄 = 22

杜绝完全不规范的缩写，避免可读性的问题：
错误示例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成condi，此类随意缩写严重降低了代码的可阅读性。

二、HTML 规范

HTML 类型

推荐使用 HTML5 的文档类型申明： .
（建议使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的属性，比如 application/xhtml+xml 在浏览器中的应用支持与优化空间都十分限）。

  • 规定字符编码
  • IE 兼容模式
  • 规定字符编码
  • doctype 大写

正确示例：

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
  5. <meta charset="UTF-8" />
  6. <title>Page title</title>
  7. </head>
  8. <body>
  9. <img src="images/company-logo.png" alt="Company" />
  10. </body>
  11. </html>

缩进

  • 缩进使用 2 个空格（一个 tab）
  • 嵌套的节点应该缩进。

    语义化标签

    HTML5 中新增很多语义化标签，所以优先使用语义化标签，避免一个页面都是 div 或者 p标签
    1. <!--正确示例-->
    2. <header></header>
    3. <footer></footer>
    4. <!--错误示例-->
    5. <div>
    6.   <p></p>
    7. </div>

三、CSS 规范

命名

  • 类名使用小写字母，以中划线分隔
  • id 采用驼峰式命名
  • less 中的变量、函数、混合、placeholder 采用驼峰式命名

ID 和 class的名称总是使用可以反应元素目的和用途的名称，或其他通用的名称。

  1. /* 不推荐：*/
  2. .fw-800 {
  3.     font-weight: 800;
  4. }
  5. .red {
  6.     color: red;
  7. }
  8. /* 推荐: */
  9. .heavy { // 若粗体只有一种，则采用heavy，如多种，则采用以上方案
  10.     font-weight: 800;
  11. }
  12. .important { // 意味着重点标记的文字
  13.     color: red;
  14. }

选择器

1) css 选择器中避免使用标签名
从结构、表现、行为分离的原则来看，应该尽量避免 css 中出现 HTML 标签，并且在 css 选择器中出现标签名会存在潜在的问题。

2) 很多前端开发人员写选择器链的时候不使用直接子选择器。有时，这可能会导致疼痛的设计问题并且有时候可能会很耗性能。然而，在任何情况下，这是一个非常不好的做法。如果你不写很通用的，需要匹配到 DOM 末端的选择器， 你应该总是考虑直接子选择器。

  • 注：直接子选择器和后代选择器的区别
    • 直接子选择器：用于选择指定标签元素的第一代子元素
    • 后代选择器：用于选择指定标签元素下的后辈元素
      1. /* 不推荐：*/
      2. .content .title {
      3. font-size: 2rem;
      4. }
      5. /* 推荐: */
      6. .content > .title {
      7. font-size: 2rem;
      8. }

      尽量使用缩写属性

      ```css / 不推荐：/ border-top-style: none; font-family: palatino, georgia, serif; font-size: 100%; line-height: 1.6; padding-bottom: 2em; padding-left: 1em; padding-right: 1em; padding-top: 0;

/ 推荐: / border-top: 0; font: 100%/1.6 palatino, georgia, serif; padding: 0 1em 2em;

  1. <a name="r2Kpx"></a>
  2. ### 每个选择器及属性独占一行
  3. ```css
  4. /* 不推荐：*/
  5. button{
  6.     width:100px;height:50px;color:#fff;background:#00a0e9;
  7. }
  8. /* 推荐: */
  9. button{
  10.   width:100px;
  11.   height:50px;
  12.   color:#fff;
  13.   background:#00a0e9;
  14. }

省略0后面的单位

  1. /* 不推荐：*/
  2. div{
  3.   padding-bottom: 0px;
  4.   margin: 0em;
  5. }
  6. /* 推荐: */
  7. div{
  8.   padding-bottom: 0;
  9.   margin: 0;
  10. }

避免使用ID选择器及全局标签选择器防止污染全局样式#

  1. /* 不推荐：*/
  2. #header{
  3.   padding-bottom: 0px;
  4.   margin: 0em;
  5. }
  6. /* 推荐: */
  7. .header{
  8.   padding-bottom: 0px;
  9.   margin: 0em;
  10. }

四、Less规范

代码组织

1)将公共less文件放置在style/less/common文件夹

  1. 例:// color.less,common.less

2)按以下顺序组织
1、@import;
2、变量声明;
3、样式声明;

  1. @import "mixins/size.less";
  2. @default-text-color: #333;
  3. .page {
  4.     width: 960px;
  5.     margin: 0 auto;
  6. }

避免嵌套层级过多

将嵌套深度限制在3级。对于超过4级的嵌套，给予重新评估。这可以避免出现过于详实的CSS选择器。
避免大量的嵌套规则。当可读性受到影响时，将之打断。推荐避免出现多于20行的嵌套规则出现

  1. /* 不推荐：*/
  2. .main{
  3.     .title{
  4.       .name{
  5.         color:#fff
  6.     }
  7.   }
  8. }
  9. /* 推荐: */
  10. .main-title{
  11.   .name{
  12.       color:#fff
  13.   }
  14. }

五、Javascript 规范

命名

1) 变量采用驼峰式命名 camelCase, 常量使用全大写，用Class采用 PascalCase
正确示例：

  1. let thisIsMyName; 
  2. const MAX_COUNT = 10;
  3. Class Person { }

2）变量声明一个函数作用域中所有的变量声明尽量提到函数首部。优先使用块级变量 let 和 const ，如无需修改的常量使用 const
**
3) 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase风格，必须遵从驼峰形式。

  1. 正确示例： localValue / getHttpMessage() / inputUserId
  2. 其中 method 方法命名必须是 动词 或者 动词+名词 形式
  3. 正确示例：saveShopCarData /openShopCarInfoDialog
  4. 错误示例：save / open / show / go

特此说明，增删查改，详情统一使用如下 5个单词，不得使用其他（目的是为了统一各个端）

  1. add / update / delete / detail / get

文末函数方法常用的动词

4) 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

  1. 正确示例： MAX_STOCK_COUNT
  2. 错误示例： MAX_COUNT

代码格式（工具格式化）

1) 使用 2 个空格进行缩进

  1. //正确示例：
  2. if (x < y) {
  3.    x += 10;
  4. } else {
  5.    x += 1;
  6. }

_
2）单行长度单行长度不得超过 100，超过部分需要换行
3）统一加分号
4）空格

  • 三元运算符’?:’前后逗号后必须要有空格
  • 代码块 ‘{‘ 前下列关键字前：else, while, catch, finally 下列关键字后：if,else, for, while, do, switch, case, try,catch, finally, with, return, typeof
  • 单行注释’//‘后（若单行注释和代码同行，则’//‘前也需要），
  • 多行注释’*’后 对象的属性值前
  • for循环，分号后留有一个空格，前置条件如果有多个，逗号后留一个空格无论是函数声明还是函数表达式，
  • ‘{‘前一定要有空格
  • 函数的参数之间

5）空行

  • 变量声明后（当变量声明在代码块的最后一行时，则无需空行）
  • 注释前（当注释在代码块的第一行时，则无需空行）
  • 定义函数前
  • 文件最后保留一个空行

6) 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。
说明：任何情形，没有必要插入多个空行进行隔开。

对象声明

1) 使用字面值创建对象

  1. 正确示例： let user = {};
  2. 错误示例： let user = new Object();

2) 使用字面量来代替对象构造器

  1. // 正确示例：
  2. var user = {
  3.     age: 0,
  4.     name: 1,
  5.     city: 3
  6. };
  7. // 错误示例：
  8. var user = new Object();
  9. user.age = 0;
  10. user.name = 0;
  11. user.city = 0;

使用 ES6,7

必须优先使用 ES6,7中新增的语法糖和函数。这将简化你的程序，并让你的代码更加灵活和可复用。
必须强制使用 ES6, ES7 的新语法，比如箭头函数、await/async ， 解构， let ，for…of 等等

括号（工具格式化）

下列关键字后必须有大括号（即使代码块的内容只有一行）：if, else, for, while, do,switch, try, catch, finally, with。

  1. // 正确示例：
  2. if (condition) {
  3.     doSomething();
  4. }
  5. // 错误示例：
  6. if (condition) doSomething();

undefined 判断

永远不要直接使用 undefined 进行变量判断；使用 typeof和字符串’undefined’对变量进行判断。

  1. // 正确示例：
  2. if (typeof person === 'undefined') {
  3. ...
  4. }
  5. // 错误示例：
  6. if (person === undefined) {
  7. ...
  8. }

条件判断和循环最多三层

条件判断能使用三目运算符和逻辑运算符解决的，就不要使用条件判断，但是谨记不要写太长的三目运算符。如果超过3 层请抽成函数，并写清楚注释。

  1. // 正确示例
  2. company === patera ? ‘Yes’ : ‘No’
  3. id && this.fetchData()
  4. // 错误示例
  5. item.sharedStatus === 0 ? '10px solid #fff' : item.sharedStatus === 1 ? '10px solid #e3effa' : item.sharedStatus === 2 ? '10px solid #f9f0ee' : item.sharedStatus === 3 ? '10px solid #eaf6df' : ''

注释规范

基础篇

1、 HTML 中的注释（分块注释）

在每一个块状元素，列表元素和表格元素后，加上一对 HTML 注释。注释格式

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
  5. <meta charset="UTF-8" />
  6. <title>Page title</title>
  7. </head>
  8. <body>
  9.   <div class="page-wrapper">
  10.     <header></header>
  11.     <main>
  12.       <!--模块一表格-->
  13.       <div class="page-module"></div>
  14.       <!--模块一列表-->
  15.       <div class="page-module"></div>
  16.     </main>
  17.     <footer></footer>
  18.   </div>
  19. </body>
  20. </html>

2、CSS 中的注释

  • 在 .html 文件中

    1. <style>
    2. div {
    3.     /* color: #fff;  */
    4.  }
    5. </style>
    6. 复制代码

  • 在 .css 文件中

    1. div {
    2.   /* color: #fff;  */
    3. }
    4. 复制代码

  • 在 .less 或 .scss 文件中

    1. div {
    2.   /* color: #fff;*/  /* 多行注释*/
    3.   // font-size: 14px; // 单行注释
    4.   background: #000;
    5. }

    注意点：

  • 在 MDN 中关于 CSS 注释只有 /* */ 一种语法。但是在 LESS 和 SCSS 中支持注释的语法和 JS 中保持一致，有单行注释 //和多行注释 /* */两种。单行注释编译之后不会被保留。

3、JS 中的注释

1）单行注释

  • 注释单独一行的情况下，注释的//后面要跟一个空格
  • 注释如果和代码同一行，代码分号结束后，要跟一个空格，注释的//后也要跟一个空格
  • 单行注释为什么有时候写在代码上方，有时候写在代码后方？一般写在代码上方的时候意为对后面一段代码的注释，而写在代码后方的时候意为对本行代码的注释
    1. // 调用函数
    2. Foo()
    3. Let maxCount = 10; // 这是一个变量
    _
    2）多行注释

    尽量使用单行注释代替多行注释

  1. /*
  2.     这是多行注释
  3.     定义一个数组
  4.  */
  5. var ary = [];

3）函数注释

  1. /**
  2.  * 方法说明
  3.  * @method 方法名
  4.  * @for 所属类名
  5.  * @param {参数类型} 参数名 参数说明
  6.  * @return {返回值类型} 返回值说明
  7.  */
  8. const onSubmit = (params = {}) => {
  9.   const result = false;
  10.     if (params) {
  11.             result = true;
  12.         }
  13.     return result;
  14. };

函数注释建议在以下几种情况使用：

  • 难于理解的代码段(涉及到算法和设计模式)
  • 可能存在错误的代码段业务逻辑强相关的代码函数注释
  • 复杂的函数，所有类，都必须进行函数注释，函数注释使用业界统一的规范，方便后续使用 jsdoc 生成文档。最好配置VSCode自动生成模板

4）必要注释

  • 公共组件使用说明
  • api 目录的接口 js 文件必须加注释
  • store 中的 state, mutation, action 等必须加注释
  • vue 文件中的 template 必须加注释，若文件较大添加 start end 注释
  • vue 文件的 methods，每个 method 必须添加注释
  • vue 文件的 data, 非常见单词要加注释

5）文件注释

  • 位于文件头部，一般包含概要、作者、版本改动信息以及修改时间等内容
    1. /*
    2. * 简述当前文件功能
    3. * @author 作者名称
    4. * @version 版本号 最近编辑时间
    5. * @description 该版本改动信息
    6. */

4、特殊标记注释

  • TODO 在该注释处有功能代码待编写，待实现的功能在说明中会简略说明
  • FIXME 在该注释处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明
  • XXX 在该注释处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明
  • NOTE 在该注释处说明代码如何工作
  • HACK 在该注释处编写得不好或格式错误，需要根据自己的需求去调整程序代码
  • BUG 在该注释处有 Bug
    1. // TODO        功能未完成，待完善
    2. // FIXME  待修复
    3. // XXX    实现方法待确认
    4. // NOTE   代码功能说明
    5. // HACK   此处写法有待优化
    6. // BUG    此处有 Bug
    7. const arr = []

注释相关插件

在这里推荐几个比较好用的注释相关的 Vscode 插件，可在 setting.json 文件下自定义设置（可通过 ‘文件—首选项—设置’，打开 Vscode 文件 settings.json ）

  • koroFileHeader 在vscode中用于生成文件头部注释和函数注释的插件

  • 文件头部添加注释

    • 在文件开头添加注释，记录文件信息/文件的传参/出参等
    • 支持用户高度自定义注释选项, 适配各种需求和注释。
    • 保存文件的时候，自动更新最后的编辑时间和编辑人
    • 快捷键：window：ctrl+alt+i，mac：ctrl+cmd+i
      1. /*
      2. * @Author: your name
      3. * @Date: 2020-09-28 10:06:44
      4. * @LastEditTime: 2020-11-17 10:49:19
      5. * @LastEditors: Please set LastEditors
      6. * @Description: In User Settings Edit
      7. * @FilePath: h5-business-platform/src/mixins/list-mixin.js
      8. */

  • 在光标处添加函数注释

    • 在光标处自动生成一个注释模板
    • 支持用户高度自定义注释选项
    • 快捷键：window：ctrl+alt+t，mac：ctrl+cmd+t
    • 快捷键不可用很可能是被占用了，参考这里
    • 可自定义默认参数
      1. /**
      2. * @description: 定义一个排序数组
      3. * @param {*} payload
      4. * @return {array} 排序完成的数组
      5. */

  • TODO Highlight 突出显示TODO，FIXME和任何关键字

    • 高亮内置关键字，可通过自定义设置覆盖外观
    • 也可自定义关键字
      1. // TODO 未完成
      2. // FIXME 待修复

      命名小结

      为了对命名规则有个全面的了解，这里列举所有的命名场景

  • 目录、文件命名全部采用kebab-case （短横线连接式， e.g. user-info ）

  • css命名
    • 类名使用小写字母，采用kebab-case，以中划线分隔
    • id 采用驼峰式命名
    • less 中的变量、函数、混合、placeholder 采用驼峰式命名
  • js命名
    • 变量采用驼峰式命名 camelCase,
    • 常量使用全大写，
    • 用Class采用 PascalCase

附： 函数方法常用的动词

  1. get 获取/set 设置,
  2. add 增加/remove 删除
  3. create 创建/destory 移除
  4. start 启动/stop 停止
  5. open 打开/close 关闭,
  6. read 读取/write 写入
  7. load 载入/save 保存,
  8. create 创建/destroy 销毁
  9. begin 开始/end 结束,
  10. backup 备份/restore 恢复
  11. import 导入/export 导出,
  12. split 分割/merge 合并
  13. inject 注入/extract 提取,
  14. attach 附着/detach 脱离
  15. bind 绑定/separate 分离,
  16. view 查看/browse 浏览
  17. edit 编辑/modify 修改,
  18. select 选取/mark 标记
  19. copy 复制/paste 粘贴,
  20. undo 撤销/redo 重做
  21. insert 插入/delete 移除,
  22. add 加入/append 添加
  23. clean 清理/clear 清除,
  24. index 索引/sort 排序
  25. find 查找/search 搜索,
  26. increase 增加/decrease 减少
  27. play 播放/pause 暂停,
  28. launch 启动/run 运行
  29. compile 编译/execute 执行,
  30. debug 调试/trace 跟踪
  31. observe 观察/listen 监听,
  32. build 构建/publish 发布
  33. input 输入/output 输出,
  34. encode 编码/decode 解码
  35. encrypt 加密/decrypt 解密,
  36. compress 压缩/decompress 解压缩
  37. pack 打包/unpack 解包,
  38. parse 解析/emit 生成
  39. connect 连接/disconnect 断开,
  40. send 发送/receive 接收
  41. download 下载/upload 上传,
  42. refresh 刷新/synchronize 同步
  43. update 更新/revert 复原,
  44. lock 锁定/unlock 解锁
  45. check out 签出/check in 签入,
  46. submit 提交/commit 交付
  47. push 推/pull 拉,
  48. expand 展开/collapse 折叠
  49. begin 起始/end 结束,
  50. start 开始/finish 完成
  51. enter 进入/exit 退出,
  52. abort 放弃/quit 离开
  53. obsolete 废弃/depreciate 废旧,
  54. collect 收集/aggregate 聚集

！！！看完了在下面回复“已读”