clean-names

整洁的命名

N1：选择描述性名称

名称应揭示意图。如果一个名称需要注释来解释，就说明它没有揭示意图。

// Bad - what is d?
const d = 86400;

// Good - obvious meaning
const SECONDS_PER_DAY = 86400;

// Bad - what does this function do?
function proc(values: number[]) {
  return values.filter((value) => value > 0);
}

// Good - intent is clear
function filterPositiveNumbers(numbers: number[]) {
  return numbers.filter((number) => number > 0);
}

N2：选择抽象层级恰当的名称

不要选择描述实现方式的名称；应选择能体现类或函数抽象层级的名称。

// Bad - too implementation-specific
function getMapOfUserIdsToNames() {
  // ...
}

// Good - abstracts the data structure
function getUserDirectory() {
  // ...
}

N3：尽可能使用标准术语

使用领域术语、设计模式术语或广为人知的约定。

// Good - uses pattern name
class UserFactory {
  create(data: unknown) {
    // ...
  }
}

// Good - uses domain term
function calculateAmortization(principal: number, rate: number, term: number) {
  // ...
}

N4：使用明确无歧义的名称

选择能明确表达函数或变量运行方式的名称。

// Bad - ambiguous
function rename(source: string, target: string) {
  // ...
}

// Good - clear what's being renamed
function renameFile(oldPath: string, newPath: string) {
  // ...
}

N5：作用域越大，名称越长

在极小的作用域中，短名称没问题。作用域越大，名称就越需要长且具有描述性。

// Good - short name for tiny scope
const total = numbers.reduce((sum, n) => sum + n, 0);

// Good - longer name for module-level constant
const MAX_RETRY_ATTEMPTS_BEFORE_FAILURE = 5;

// Bad - short name at module level
const MAX = 5;

N6：避免编码式命名

不要将类型或作用域信息编码到名称中。现代编辑器已使这种做法没有必要。

// Bad - Hungarian notation
const strName = "Alice";
const arrUsers: string[] = [];
const nCount = 0;

// Good - clean names
const name = "Alice";
const users: string[] = [];
const count = 0;

// Bad - interface prefix
interface IUserRepository {
  findById(id: string): Promise<unknown>;
}

// Good - just name it
interface UserRepository {
  findById(id: string): Promise<unknown>;
}

N7：名称应描述副作用

如果函数执行的操作超出了名称所暗示的范围，那么这个名称就具有误导性。

const configStore = new Map<string, string>();

// Bad - name doesn't mention file creation
function getConfig(configPath: string) {
  if (!configStore.has(configPath)) {
    configStore.set(configPath, "{}"); // Hidden side effect!
  }
  return JSON.parse(configStore.get(configPath) ?? "{}");
}

// Good - name reveals behavior
function getOrCreateConfig(configPath: string) {
  if (!configStore.has(configPath)) {
    configStore.set(configPath, "{}");
  }
  return JSON.parse(configStore.get(configPath) ?? "{}");
}

快速参考

规则	原则	示例
N1	描述性名称	SECONDS_PER_DAY 而非 d
N2	合适的抽象层级	getUserDirectory() 而非 getMapOf...
N3	标准术语	UserFactory、calculateAmortization
N4	明确无歧义	renameFile(oldPath, newPath)
N5	名称长度与作用域相匹配	循环中用短名称，全局变量用长名称
N6	不使用编码式命名	users 而非 arrUsers
N7	描述副作用	getOrCreateConfig()