大猿猴的前端世界

Appearance

本篇先提供市面上的参考规范链接，接着分别对HTML5、CSS、JS常用的代码规范列举说明，最后简单介绍了下文件命名规范和格式规范。

市面规范 ​

HTML&CSS规范 ​

JS规范 ​

国内大厂规范 ​

HTML5规范 ​

  • 必须设置字符集编码

  • 默认样式类型是text/css，脚本类型是text/javascript，无需显式声明

  • 块标签间的嵌套约束，如p不能嵌套hx、div

  • 行内元素不包含块元素

  • 单标签不必使用结束标签

  • 标签名、属性名使用小写字母

  • 属性顺序：id、class、name、data-xxx、src、type、for、href、title、alt、aria-xxx、role

  • 属性值使用双引号

  • 使用转义字符代替实体符号

  • 省略图片、样式、脚本、媒体等文件URL的协议部分，如http:或https:。这称为protocol-relative URL，好处是无论使用HTTPS还是HTTP访问页面，浏览器都会以相同协议请求页面资源，同时节省空间大小

  • 多媒体标签必须加alt属性，有助于提示

  • 有下载需求的图片采用img标签实现，无下载需求的图片采用CSS背景图实现

  • hx标签切勿出现断层

  • PC网站的版心宽度一般在1024px到1440px之间

  • 一次缩进是2个空格

CSS规范 ​

选择器命名规范 ​

  • 命名简短，且具有语义性，能传达结构和功能信息

  • 推荐多类模式，如btn、btn-primary、btn-waring

  • 借鉴BEM命名结构（如Block-Element）、面向对象的CSS（如容器和内容的分离思想）、原子化的CSS（比如下点介绍的命名就体现了原子化）

    html
    <!-- 容器和内容分离 -->
<div class="container">
  <h2>xxx</h2>
</div>
<style>
  .container h2 {}
</style>
<!-- 调整为 -->
<div class="container">
  <h2 class="title">xxx</h2>
</div>
<style>
  .title {}
</style>

  • 使用小写字母、数字、短横杆-命名

    w100
h100
mt20
mb20
ml20
mr20
pt20
pb20
pl20
pr20
tl
tr
tc
fl
fr
bg-xxx
c-xxx
fs-xx
btn-xxx

规则集格式规范 ​

  • 当规则或声明块中有多个声明时，每个声明独占一行
  • 使用组合选择器时，每个选择器独占一行
  • 在规则或声明块的左大括号{前加一个空格
  • 在属性的冒号:后面加上一个空格，前面不加空格
  • 当一个属性有多个属性值时，以逗号,分隔属性值，每个逗号后添加一个空格，当单个属性值过长时，每个属性值独占一行
  • 在每个声明后面都以分号;结尾
  • 规则或声明块的右大括号}独占一行
  • 每个规则声明间用空行分隔
  • 最外层的引号使用单引号'

其他 ​

  • 属性书写顺序：布局 > 盒模型 > 文本 > 字体 > 视觉动效(背景、边框、阴影、转换、动画、过渡等)
  • 属性使用简写属性
  • 值简写：如color: #ffcc00;可写为color: #fc0;，opacity: 0.5;可写为opacity: .5;，border-width: 0px;可写为border-width: 0;
  • 能用类选择器就绝不用ID选择器，避免使用标签选择器
  • 减少后代选择器层级
  • 嵌套层级不超过3层
  • 添加必要的注释，作说明、划分
  • 选择器、属性名，属性值使用小写字母
  • 布局上尽可能地保持正常流
  • 遵循单一功能原则：通用样式按单一功能划分
  • 注意样式的作用范围

Javascript规范 ​

  • 私有变量以_开头

  • 常量使用大写

  • 使用驼峰式命名模块、对象、函数、属性、变量

  • 使用帕斯卡式命名构造函数、类

  • 方法常用命名单词，init、load、bind、validate、query、add、delete、update、render、build、on、emit、save、clear、set、get、reset、upload、download、has、is、open、close。不能同事一看就说What the fuck，至少能看出是做什么，且保持函数功能只做一件事

  • 缩略词的所有字符应当一并大写或一并小写

    javascript
    getSVG()
svgParser()

  • css从js脱离，使用classList

  • html从js脱离，使用template

  • 避免全局变量，使用模块化

  • 代码与数据分离

  • 逻辑与事件处理分离

  • 重复代码超过连续的10行，建议抽取

  • 声明变量放在最顶部

  • 避免在一个函数中声明函数

  • 避免在条件或循环语句中声明函数，一来代码维护性差，二来可能造成全局冲突

  • IIFE以!开始，;结束

    javascript
    !function (global) {
  'use strict';
  const originMyModule = global.myModule;
  
  // 定义一个同名模块
  function myModule(options) {
    console.log('myModule.')
  }
  // 添加noConflict方法
  myModule.noConflict = function() {
    // 引用原模块，保证在同名模块下可以正常使用旧同名模块内容
    global.myModule = originMyModule;
    return myModule;
  };

  global.myModule = myModule;
}(this);

  • 不持this的引用，使用bind函数，避免闭包

    javascript
    // bad
function () {
  var _this = this;
  return function () {
    console.log(_this);
  };
}
// good
function () {
  return function () {
    console.log(this);
  }.bind(this);
}

  • 扩展内置JS原型

    javascript
    // 正例
ArrayUtil.forEach(arr, function(){

})
// 反例
Array.prototype.forEach = function(){

}

  • 尽量让null和undefined的含义相同。也就是说，不要让用户或开发者去区分变量是null还是undefined

  • 导入模块顺序

    主框架依赖

    第三方或自行封装的依赖

    独有依赖，包括api、组件、枚举、样式

  • 错误处理

    5XX错误使用统一提示

    4XX错误使用具体提示

    脚本错误不提示

  • 请求头Content-Type

    值一般设置为application/json，不推荐application/x-www-form-urlencoded。当涉及文件类型数据时改用multipart/form-data，比如上传

  • 引用js脚本需添加迭代版本号

  • 使用TODO:标记待办、FIXME:标记bug

文件命名规范 ​

可以是驼峰命名法(小驼峰)，也可以是帕斯卡命名法(大驼峰)。关键在于一个项目只能使用其中一种，不混用，无论是页面，还是组件。个人建议使用小驼峰命名法。

格式规范 ​

  • 运算符

    二元运算符两个操作数之间必须使用空格，但一元运算符与其操作数间不能有空格

    javascript
    let a = !arr.length;
a = b + c;

    如果需要换行，运算符必须放在新行的开头

    javascript
    // 正例
if(a === 1
  && b === 2
  && c === 3
) {

}
// 反例
if(a === 1 && 
  b === 2 && 
  c === 3) {

}

  • 大括号

    在 { 前必须有1个空格

    javascript
    if(true) {

}

function func() {

}

    如果代码块只有一行，{} 不能被省略

    javascript
    if(typeOf func === 'function') {
  func();
}

  • 小括号

    在函数声明、函数调用时，函数名称和 ( 间不能有空格

    javascript
    function func() {

}
func();

  • 小括号、中括号

    ( 和 [ 之后、 ) 和 ] 之前不能有空格

    javascript
    // 正例
func(param1, param2);
get(list[0]);
// 反例
func( param1, param2 );
get(list[ 0 ]);

  • 括号

    如果括号中的内容有多行，必须为 )、 ]、 } 另开一个新行，并使新行与 (、 [、 { 所在行的缩进相对应

    javascript
    // 正例
if (product) {
  product.load();
  if (user.isAuthenticated()
    && user.isInRole('admin')
    && user.hasAuthority('add-admin')
  ) {
    sendProduct(user, product);
  }
}
const arr = [
  'candy', 'sugar'
];

// 反例
if (product) {
  product.load();
  if (user.isAuthenticated()
    && user.isInRole('admin')
    && user.hasAuthority('add-admin')) {
    sendProduct(user, product);
  }
}
const arr = [
    'candy', 'sugar'
  ];

  • 冒号

    在创建对象的语句中，: 后必须加一个空格，: 前不能有空格

    javascript
    const obj = {
  a: 1,
  b: 2,
}

  • 逗号、分号

    , 和 ; 前不能有空格或换行

    javascript
    // 正例
func(1,2);
const obj = {
  a: 1,
  b: 2,
}
// 反例
func(1 ,2) ;
const obj = {
  a: 1
  ,b: 2
}

  • 分号：函数、对象、数组声明后不需加分号

  • 空格：每行代码后不能有尾随空格

  • 换行：必须在语句的结尾换行

最后 ​

一定有同学会说，这么多规范谁记得住呀？我们对这些规范有一个认识即可，不必记。下篇会讲如何对我们的项目进行自动化规范检查、纠正，以及如何一键集成自动化规范到项目中。

Last updated: