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	適切な抽象度	getMapOf... ではなく getUserDirectory()
N3	標準的な用語	UserFactory、calculateAmortization
N4	曖昧さがない	renameFile(oldPath, newPath)
N5	スコープに合った長さ	ループ内は短く、グローバル変数は長く
N6	エンコーディングなし	arrUsers ではなく users
N7	副作用を明示	getOrCreateConfig()