前端规约

内含 HTML、CSS、JavaScript、TypeScript、React、Vue、Nodejs 编码规约和工程规约,包括 Git 规约、文档通用规约、更新日志规约、前后端协作规约、安全研发规约、云研发规约,以及配套工具及流程保障。

基本篇

JavaScript 规范

迭代器

请使用高阶函数替代迭代器,尽量保持原数组的不变性(无副作用)

[eslint: no-iterator no-restricted-syntax]

使用 map() / every() / filter() / find() / findIndex() / reduce() / some() / … 遍历数组

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const numbers = [1, 2, 3, 4, 5];

// ❌
let sum = 0
for (let num of numbers) {
sum += num
}

// NOT BAD
let sum = 0
numbers.forEach(num => {
sum += num
})

// ✅
const sum = numbers.reduce((total, num) => total + num, 0)

命名篇

变量命名

常规变量

常规变量:1 主体应该是名词,2 不应该携带类型,3 抽象而非具体,否则会导致“抽象泄露”,换言之修改变量类型,所有使用处均需改变。其他命名规则见下方:

规则一:变量主体应该是一个名词,故不应该动词开头

The first word of a variable name should be a noun or adjective (not a verb) to avoid confusion with functions。变量应该是名词或形容词,而非动词避免和函数命名冲突
eslint: variable-name-starts-with-non-verb

Bad
1
2
3
4
/** 目标链接 */
const goPage = 'https://yuque.antfin-inc.com/industryprod-hz/nopbol/sookzo';
const encodeDetailInfo = encodeURIComponent(jsonStringifySafely(detailInfo));
const parseDetailInfo = jsonParseSafely(detailInfo);

违反命名规范,应该是动词开头,doSth 是函数命名规则。

Good
1
2
3
4
/** 目标链接 */
const targetUrl ...;
const encodedDetailInfo ...;
const parsedDetailInfo ...;
规则二:命名不应该携带类型
Bad
1
2
3
interface IResultObj {
success: boolean;
};
Good
1
2
3
interface IResult {
success: boolean;
};

特殊模式变量

debounce / throttle timer

建议以 DebounceTimerThrottleTimer 结尾,和设计模式类名命名一样,一样能看出来其作用是防抖还是节流。

Bad
1
2
3
4
5
6
7
8
9
10
deriveDataFromProps(nextProps) {
if (nextProps.update !== this.props.update || nextProps.configMode !== this.props.configMode) {
// 接口刷新慢于update变更导致多次触发
fetchLockTimer && clearTimeout(fetchLockTimer);

fetchLockTimer = setTimeout(() => {
this.initPage(nextProps);
}, 200);
}
},
Good

fetchLockTimer => initPageDebounceTimer

1
2
3
4
5
6
7
8
9
10
deriveDataFromProps(nextProps) {
if (nextProps.update !== this.props.update || nextProps.configMode !== this.props.configMode) {
// 接口刷新慢于update变更导致多次触发
initPageDebounceTimer && clearTimeout(initPageDebounceTimer);

initPageDebounceTimer = setTimeout(() => {
this.initPage(nextProps);
}, 200);
}
},

复数命名

TODO: eslint rule enforce-postfix-to-plural-variables
集合(map、set、array 不包括字面量对象)变量命名规则:

  • 可数名词加 s,比如 cards items
  • 不可数名词加 List,比如 extra => extraList
  • 二维数组怎么命名:可数名词 contactsList 不可数名词 extraLists
Bad
1
const imagelist = ...;
Good
1
const images = ...;
Bad
1
2
3
4
const ActivityStatusEnumArr = [
'ON',
'OFF',
]

该命名的问题:从后缀 Arr 就定死了底层的数据结构一定是数组(抽象泄露),不具备扩展性。

Good
1
2
3
4
5
6
7
8
9
10
const activityStatusList = [
'ON',
'OFF',
]

// 或
enum ActivityStatusEnum {
'ON',
'OFF',
}