code-spec/references/js&ts.base.md

基础代码规范 [JsTs.Base]

下面是 JS/TS 的代码规范

常量名使用大写加下划线命名（UPPER_CASE），单词间以下划线分隔 [JsTs.Base.ConstUpperCase]

• 不检查 nodejs 的导包定义，比如 const fs = require("fs")
• 常量检查只需检查 const 声明的静态值，但是不包含对象和函数

Example: 常量命名

Good: 使用大写加下划线

const ROLE_ADMIN = 1;

Bad: 使用小驼峰

const roleAdmin = 1;

函数名使用小驼峰命名 [JsTs.Base.FuncLowerCamel]

• severity warn

Example: 函数命名

Good: 使用小驼峰

function getUserInfo() {
  // ...
}

Bad: 使用全小写

function getuserinfo() {
  // ...
}

禁止使用字面量魔法数字 [JsTs.Base.NoMagicVar]

• severity warn

• 仅检查数字字面量和正则字面量，不检查布尔、对象、函数、数组、字符串字面量
• 仅检查含义不明确的数字，如 0、1、2 等；
• throw / new Error 的错误信息无需审查
• console.*（log / error / warn / info / debug / trace）的内容无需审查
• 语义自明的数量类数字无需抽取常量，例如：时间戳、毫秒时长、元素数量、尺寸等一眼可理解的值

Example: 魔法数字

Good: 使用常量替代魔法数字

const ROLE_ADMIN = 1;

if (user.role === ROLE_ADMIN) {
  // ...
}

Bad: 使用字面量魔法数字

if (user.role === 1) {
  // ...
}

基于 JsTs.Base.NoMagicVar 抽离的静态常量需要放在对应文件里 [JsTs.Base.ConstantsDefinition]

• severity error

• 需要放在指定模块的 constants 文件里
• constants 命名规则: user.constants.js 或者 user.constants.ts

Example: 常量定义位置

Good: 常量放在对应模块的 constants 文件

// user.constants.js
const ROLE_ADMIN = 1; // 这是 user 模块需要的

Bad: 常量放在错误模块的 constants 文件

// class.constants.js
const ROLE_ADMIN = 1; // 这是 user 模块需要的

class 和 interface 命名使用大驼峰命名 [JsTs.Base.ClassNaming]

• severity warn

Example: 类和接口命名

Good: 使用大驼峰

class UserInfo {
  // ...
}

Bad: 使用全小写

class userinfo {
  // ...
}

变量名使用小驼峰或者蛇形命名 [JsTs.Base.VarNaming]

• severity warn

• 需要注意的是从 require 导入的变量不受检查
• 私有属性可以使用 _ 开头,比如 this._fromFeatureRecommendEntry

Example: 变量命名

Good: 使用小驼峰或蛇形命名

let userName = "John";
let user_name = "John";

Bad: 使用大驼峰

let Username = "John";

单文件代码不超过 700 行 [JsTs.Base.CodeNotMoreThan700Lines]

• includes added|*

Example: 文件行数

Good: 代码不超过 700 行

// 代码不超过 700 行

Bad: 代码超过 700 行

// 代码超过 700 行

单个函数或方法不能超出 300 行 [JsTs.Base.FuncNotMoreThan300Lines]

Example: 函数行数

Good: 函数不超过 300 行

function getUserInfo() {
  // ... 小于等于 300
}

Bad: 函数超过 300 行

• includes added|*

function getUserInfo() {
  // ... 大于 300
}

复杂的逻辑判断要添加注释 [JsTs.Base.ComplexLogic]

• severity warn

• 逻辑判断的复杂度大于等于 3 个的要添加注释

Example: 复杂逻辑注释

Good: 复杂逻辑添加注释

// 逻辑判断复杂度大于等于 3 个
if (a && b || c) {
  // ...
}

Bad: 复杂逻辑未添加注释

if (a && b && c && d) {
  // ...
}

复杂的函数要添加注释 [JsTs.Base.ComplexFunc]

• severity warn

Example: 复杂函数注释

Good: 复杂函数添加注释

• includes added|*

/**
 * 复杂的算法逻辑
 */
function complexFunc() {
  // ... 
}

Bad: 复杂函数未添加注释

• includes added|*

function complexFunc() {
  // ... 
}