Skip to content

Latest commit

 

History

History
473 lines (298 loc) · 11.1 KB

前端开发规范.md

File metadata and controls

473 lines (298 loc) · 11.1 KB

开发规范

WXML

  1. class, id 命名规范：一致小写，尽量英文，中横线连接
  2. 块级元素换行
  3. 关注点分离，不可在 wxml 中嵌入样式、行为

WXSS

  1. 注释风格
/* H1 */
/** H2 */
/*** H3 */
/**** H4 */
/**** H4 End */
/*** H3 End */
/** H2 End */
/* H1 End */
  1. 书写顺序：
  1. 位置属性(position, top, right, z-index, display, float等)
  2. 大小(width, height, padding, margin)
  3. 文字系列(font, line-height, letter-spacing, color- text-align等)
  4. 背景(background, border等)
  5. 其他(animation, transition等)
  1. 使用CSS缩写属性。比如padding,margin,font等等，这样精简代码同时又能提高用户的阅读体验
  2. 去掉小数点前的“0”
  3. 简写命名
  4. 16进制颜色代码缩写，如果可以就简写
  5. 选择器命名：使用中横线，一律使用小写，尽量使用英文，不随意缩写
  6. 不乱使用id
  7. 每个样式之间以空行间隔
  8. 恰当使用注释

JS

代码风格

缩进

2 个空格。

空格

二元运算符两侧必须有一个空格，一元运算符与操作对象之间不允许有空格。

用作代码块起始的左花括号 { 前必须有一个空格。

on / switch / do / try / catch / finally 关键字后，必须有一个空格。

在对象创建时，属性中的 : 之后必须有空格，: 之前不允许有空格。

函数声明、具名函数表达式、函数调用中，函数名和 ( 之间不允许有空格。

, 和 ; 前不允许有空格。

一般情况下，() 和 [] 内紧贴括号部分不允许有空格。

换行

每个独立语句结束后必须换行。

每行不得超过 120 个字符。超长的不可分割的代码允许例外，比如复杂的正则表达式。长字符串不在例外之列。

运算符处换行时，运算符必须在新行的行首。

在函数声明、函数表达式、函数调用、对象创建、数组创建、for语句等场景中，不允许在 , 或 ; 前换行。

不同行为或逻辑的语句集，使用空行隔开，更易阅读。

在语句的行长度超过 120 时，根据逻辑条件合理缩进。

语句

不得省略语句结束的分号。

在 if / else / for / do / while 语句中，即使只有一行，也不得省略块 {...}。

函数定义结束不允许添加分号。

命名

变量 ,函数, 函数的 参数 使用 Camel命名法。

常量 使用 全部字母大写，单词间下划线分隔 的命名方式。

类 使用 Pascal命名法。

类的 方法 / 属性 使用 Camel命名法。

枚举变量 使用 Pascal命名法，枚举的属性 使用 全部字母大写，单词间下划线分隔 的命名方式。

命名空间 使用 Camel命名法。

由多个单词组成的缩写词，在命名中，根据当前命名法和出现的位置，所有字母的大小写与首字母的大小写保持一致。

类名 使用 名词。

函数名 使用 动宾短语。

boolean 类型的变量使用 is 或 has 开头。

Promise对象 用 动宾短语的进行时 表达。

注释

单行注释

必须独占一行。//

多行注释

/** … */ 尽量避免

文档化注释

此前必须空一行

文件注释

[强制] 文件顶部必须包含文件注释，用 @file 标识文件说明。

示例：

/**
 * @file Describe the file
 * @author author-name([email protected])
 *         author-name2([email protected])
 */

[建议] 文件注释中可以用 @author 标识开发者信息。

函数/方法注释

[强制] 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。

[强制] 参数和返回值注释必须包含类型信息和说明。

示例：

/**
 * 函数描述
 *
 * @param {string} p1 参数1的说明
 * @param {string} p2 参数2的说明，比较长
 *     那就换行了.
 * @param {number=} p3 参数3的说明（可选）
 * @return {Object} 返回值描述
 */
function foo(p1, p2, p3) {
    var p3 = p3 || 10;
    return {
        p1: p1,
        p2: p2,
        p3: p3
    };
}

[强制] 对 Object 中各项的描述， 必须使用 @param 标识。

常量注释

[强制] 常量必须使用 @const 标记，并包含说明和类型信息。

示例：

/**
 * 常量说明
 *
 * @const
 * @type {string}
 */
var REQUEST_URL = 'myurl.do';

细节注释

对于内部实现、不容易理解的逻辑说明、摘要信息等，我们可能需要编写细节注释。

[建议] 细节注释遵循单行注释的格式。说明必须换行时，每行是一个单行注释的起始。

示例：

function foo(p1, p2, opt_p3) {
    // 这里对具体内部逻辑进行说明
    // 说明太长需要换行
    for (...) {
        ....
    }
}

[强制] 有时我们会使用一些特殊标记进行说明。特殊标记必须使用单行注释的形式。下面列举了一些常用标记：

解释：

  1. TODO: 有功能待实现。此时需要对将要实现的功能进行简单说明。
  2. FIXME: 该处代码运行没问题，但可能由于时间赶或者其他原因，需要修正。此时需要对如何修正进行简单说明。
  3. HACK: 为修正某些问题而写的不太好或者使用了某些诡异手段的代码。此时需要对思路或诡异手段进行描述。
  4. XXX: 该处存在陷阱。此时需要对陷阱进行描述。

语言特性

变量

[强制] 变量在使用前必须通过 var 定义。

[强制] 每个 var 只能声明一个变量。

[强制] 变量必须 即用即声明，不得在函数或其它形式的代码块起始位置统一声明所有变量。

条件

[强制] 在 Equality Expression 中使用类型严格的 ===。仅当判断 null 或 undefined 时，允许使用 == null。

[建议] 尽可能使用简洁的表达式。

示例：

// 字符串为空

// good
if (!name) {
    // ......
}

// bad
if (name === '') {
    // ......
}
// 字符串非空

// good
if (name) {
    // ......
}

// bad
if (name !== '') {
    // ......
}
// 数组非空

// good
if (collection.length) {
    // ......
}

// bad
if (collection.length > 0) {
    // ......
}
// 布尔不成立

// good
if (!notTrue) {
    // ......
}

// bad
if (notTrue === false) {
    // ......
}
// null 或 undefined

// good
if (noValue == null) {
  // ......
}

// bad
if (noValue === null || typeof noValue === 'undefined') {
  // ......
}

[建议] 按执行频率排列分支的顺序。

[建议] 对于相同变量或表达式的多值条件，用 switch 代替 if。

[建议] 对有序集合进行遍历时，缓存 length。

示例：

for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    // ......
}

循环

[建议] 不要在循环体中包含函数表达式，事先将函数提取到循环体外。

[建议] 对循环内多次使用的不变值，在循环外用变量缓存。

[建议] 对有序集合进行顺序无关的遍历时，使用逆序遍历。（逆序遍历可以节省变量，代码比较优化。）

类型

类型检测

[建议] 类型检测优先使用 typeof。对象类型检测使用 instanceof。null 或 undefined 的检测使用 == null。

示例：

// string
typeof variable === 'string'

// number
typeof variable === 'number'

// boolean
typeof variable === 'boolean'

// Function
typeof variable === 'function'

// Object
typeof variable === 'object'

// RegExp
variable instanceof RegExp

// Array
variable instanceof Array

// null
variable === null

// null or undefined
variable == null

// undefined
typeof variable === 'undefined'
类型转换

[建议] 转换成 string 时，使用 + ''。

[建议] 转换成 number 时，通常使用 +。

[建议] string 转换成 number，要转换的字符串结尾包含非数字并期望忽略时，使用 parseInt。

[强制] 使用 parseInt 时，必须指定进制。

[建议] 转换成 boolean 时，使用 !!。

[建议] number 去除小数点，使用 Math.floor / Math.round / Math.ceil，不使用 parseInt。

字符串

[强制] 字符串开头和结束使用单引号 '。

[建议] 使用 数组 或 + 拼接字符串。

解释：

  1. 使用 + 拼接字符串，如果拼接的全部是 StringLiteral，压缩工具可以对其进行自动合并的优化。所以，静态字符串建议使用 + 拼接。
  2. 在现代浏览器下，使用 + 拼接字符串，性能较数组的方式要高。
  3. 如需要兼顾老旧浏览器，应尽量使用数组拼接字符串。

示例：

// 使用数组拼接字符串
var str = [
    // 推荐换行开始并缩进开始第一个字符串, 对齐代码, 方便阅读.
    '<ul>',
        '<li>第一项</li>',
        '<li>第二项</li>',
    '</ul>'
].join('');

// 使用 + 拼接字符串
var str2 = '' // 建议第一个为空字符串, 第二个换行开始并缩进开始, 对齐代码, 方便阅读
    + '<ul>',
    +    '<li>第一项</li>',
    +    '<li>第二项</li>',
    + '</ul>';

[建议] 复杂的数据到视图字符串的转换过程，选用一种模板引擎。

对象

[强制] 使用对象字面量 {} 创建新 Object。

[强制] 对象创建时，如果一个对象的所有 属性 均可以不添加引号，则所有 属性 不得添加引号。

[强制] 对象创建时，如果任何一个 属性 需要添加引号，则所有 属性 必须添加 '。

[建议] 属性访问时，尽量使用 .。

[建议] for in 遍历对象时, 使用 hasOwnProperty 过滤掉原型中的属性。

数组

[强制] 使用数组字面量 [] 创建新数组，除非想要创建的是指定长度的数组。

[强制] 遍历数组不使用 for in。（数组对象可能存在数字以外的属性, 这种情况下 for in 不会得到正确结果.）

[建议] 不因为性能的原因自己实现数组排序功能，尽量使用数组的 sort 方法。

[建议] 清空数组使用 .length = 0。

函数

函数长度

[建议] 一个函数的长度控制在 50 行以内。（特定算法等不可分割的逻辑允许例外。）

参数设计

[建议] 一个函数的参数控制在 6 个以内。

[建议] 通过 options 参数传递非数据输入型参数。

闭包

[建议] 在适当的时候将闭包内大对象置为 null。

reference