coding-philosophy（编码哲学）

Coding Philosophy

Overview

This skill enforces the core coding philosophy for this project: immutability, predictable structure, functional transformations, test-driven development, clean deletion, and simplicity. All code should follow these principles to maintain consistency, testability, and clarity.

Guiding Principles: YAGNI + SOLID + DRY + KISS

Follow these software engineering principles, deferring to Occam's Razor/KISS whenever principles conflict:

KISS (Keep It Simple, Stupid) - The Tiebreaker

When principles conflict, always choose the simpler solution. Occam's Razor applies to code: the simplest solution that works is usually correct.

// KISS: Simple direct approach
const isAdmin = user.role === "admin";

// Over-engineered: Abstraction without value
const isAdmin = RoleChecker.getInstance().checkRole(user, RoleTypes.ADMIN);

YAGNI (You Ain't Gonna Need It)

Don't build features, abstractions, or flexibility you don't need right now.

// Correct: Solve today's problem
const formatDate = (date: Date) => date.toISOString().split("T")[0];

// Wrong: Building for hypothetical future needs
const formatDate = (date: Date, format?: string, locale?: string, timezone?: string) => {
  // 50 lines handling cases that may never be used
};

DRY (Don't Repeat Yourself) - With KISS Constraint

Extract duplication only when:

1. The same logic appears 3+ times
2. The abstraction is simpler than the duplication
3. The extracted code has a clear single purpose

// DRY + KISS: Extract when clearly beneficial
const formatPlayerName = (first: string, last: string) => `${first} ${last}`;

// Anti-pattern: Premature abstraction for 2 usages
// Keep inline if simpler and only used twice

SOLID Principles - Applied Pragmatically

Apply SOLID when it reduces complexity, not dogmatically:

// Good SRP: Each function has one job
const validateEmail = (email: string) => EMAIL_REGEX.test(email);
const formatEmail = (email: string) => email.toLowerCase().trim();

// Over-applied SRP: Don't split a simple 3-line function into 3 files

Decision Framework

When unsure, ask in order:

1. Do I need this now? (YAGNI) → If no, don't build it
2. Is there a simpler way? (KISS) → Choose the simpler option
3. Am I repeating myself 3+ times? (DRY) → Extract if the abstraction is simpler
4. Does this function do one thing? (SOLID-SRP) → Split only if clearer

Core Principles

1. Immutability First

Never mutate data. Always create new references.

// Correct - spread creates new object
const updated = { ...user, name: "New Name" };

// Incorrect - mutation
user.name = "New Name";

2. Function Structure Ordering

All functions, hooks, and components follow a strict ordering:

1. Variable definitions and derived state (const, useState, useMemo, useCallback)
2. Side effects (useEffect, function calls with no return value)
3. Return statement

3. Functional Transformations

Use map, filter, reduce instead of imperative loops and mutations.

// Correct - functional transformation
const names = users.map(u => u.name);

// Incorrect - imperative mutation
const names = [];
users.forEach(u => names.push(u.name));

4. Test-Driven Development (TDD)

Always write failing tests before implementation code. This is mandatory, not optional.

TDD Cycle:
1. RED: Write a failing test that defines expected behavior
2. GREEN: Write the minimum code to make the test pass
3. REFACTOR: Clean up while keeping tests green

// Step 1: Write the failing test FIRST
describe("formatPlayerName", () => {
  it("should format first and last name", () => {
    expect(formatPlayerName("John", "Doe")).toBe("John Doe");
  });

  it("should handle empty last name", () => {
    expect(formatPlayerName("John", "")).toBe("John");
  });
});

// Step 2: THEN write implementation to make tests pass
const formatPlayerName = (first: string, last: string): string =>
  last ? `${first} ${last}` : first;

TDD is non-negotiable because it:

• Forces you to think about the API before implementation
• Ensures every feature has test coverage
• Prevents over-engineering (you only write what's needed to pass tests)
• Documents expected behavior

5. Clean Deletion

Delete old code completely. No deprecation warnings, migration shims, or backward-compatibility layers unless explicitly requested.

// Correct: Remove the old code entirely
// (Old function is gone, new function exists)
const calculateScore = (player: Player): number => player.stats.overall;

// Wrong: Keeping deprecated versions around
/** @deprecated Use calculateScore instead */
const getPlayerScore = (player: Player): number => calculateScore(player);
const calculateScoreV2 = (player: Player): number => player.stats.overall;

Clean deletion rules:

• When replacing code, delete the old version completely
• Never create V2, New, or Old suffixed functions/variables
• Never add @deprecated comments - just remove the code
• Never write migration code unless explicitly asked
• Trust git history for recovery if needed

Why clean deletion:

• Reduces cognitive load (one way to do things)
• Prevents confusion about which version to use
• Keeps bundle size small
• YAGNI: If no one is using it, delete it

Detailed Guidelines

For comprehensive examples and patterns, see the reference files:

• references/immutable-patterns.md - Detailed immutable patterns with reduce, spread, and functional transformations
• references/function-structure.md - Function ordering rules and examples for hooks, utilities, and components

Quick Reference

Variable Declaration

Array Operations

Object Operations

Building Lookup Objects

// Correct - reduce with spread
const lookup = items.reduce(
  (acc, item) => ({ ...acc, [item.id]: item }),
  {} as Record<string, Item>
);

// Incorrect - forEach with Map.set
const lookup = new Map();
items.forEach(item => lookup.set(item.id, item));

Conditional Values

// Correct - ternary expression
const status = isComplete ? "done" : "pending";

// Incorrect - let with reassignment
let status = "pending";
if (isComplete) {
  status = "done";
}

Hook Structure Example

export const usePlayerData = (playerId: string) => {
  // 1. VARIABLES & STATE (first)
  const [isLoading, setIsLoading] = useState(true);
  const { data } = useQuery(GetPlayerDocument, { variables: { playerId } });

  const playerName = useMemo(() => data?.player?.name ?? "Unknown", [data]);

  const handleRefresh = useCallback(() => {
    refetch();
  }, [refetch]);

  // 2. SIDE EFFECTS (second)
  useEffect(() => {
    console.log("Player loaded:", playerName);
  }, [playerName]);

  // 3. RETURN (last)
  return { playerName, isLoading, handleRefresh };
};

Container Component Example

const PlayerCardContainer: React.FC<Props> = ({ playerId }) => {
  // 1. VARIABLES & STATE
  const { data, loading } = useQuery(GetPlayerDocument, { variables: { playerId } });
  const { colors } = useTheme();

  const formattedStats = useMemo(
    () => data?.stats?.map(s => ({ ...s, display: formatStat(s) })) ?? [],
    [data?.stats]
  );

  const handlePress = useCallback(() => {
    router.push(`/players/${playerId}`);
  }, [playerId]);

  // 2. SIDE EFFECTS (none in this example)

  // 3. RETURN
  return (
    <PlayerCardView
      stats={formattedStats}
      colors={colors}
      loading={loading}
      onPress={handlePress}
    />
  );
};

Utility Function Example

export const calculateTeamRankings = (
  players: readonly Player[]
): readonly TeamRanking[] => {
  // 1. VARIABLES & DERIVED VALUES
  const validPlayers = players.filter(p => p.team && p.score != null);

  const teamScores = validPlayers.reduce(
    (acc, player) => ({
      ...acc,
      [player.team.id]: {
        teamId: player.team.id,
        totalScore: (acc[player.team.id]?.totalScore ?? 0) + player.score,
        count: (acc[player.team.id]?.count ?? 0) + 1,
      },
    }),
    {} as Record<string, { teamId: string; totalScore: number; count: number }>
  );

  const rankings = Object.values(teamScores).map(t => ({
    teamId: t.teamId,
    avgScore: t.totalScore / t.count,
  }));

  const sorted = [...rankings].sort((a, b) => b.avgScore - a.avgScore);

  // 2. NO SIDE EFFECTS IN PURE FUNCTIONS

  // 3. RETURN
  return sorted;
};

Anti-Patterns to Avoid

Never use let for conditional assignment

// Wrong
let result;
if (condition) {
  result = valueA;
} else {
  result = valueB;
}

// Correct
const result = condition ? valueA : valueB;

Never mutate arrays

// Wrong
const items = [];
data.forEach(d => items.push(transform(d)));

// Correct
const items = data.map(d => transform(d));

Never use Map when Record suffices

// Wrong
const lookup = new Map<string, User>();
users.forEach(u => lookup.set(u.id, u));
const user = lookup.get(userId);

// Correct
const lookup = users.reduce(
  (acc, u) => ({ ...acc, [u.id]: u }),
  {} as Record<string, User>
);
const user = lookup[userId];

Never sort in place

// Wrong - mutates original
const sorted = items.sort((a, b) => a.value - b.value);

// Correct - creates new array
const sorted = [...items].sort((a, b) => a.value - b.value);

Never place useEffect before variable definitions

// Wrong
useEffect(() => {
  /* ... */
}, [value]);
const value = useMemo(() => calculate(), [dep]);

// Correct
const value = useMemo(() => calculate(), [dep]);
useEffect(() => {
  /* ... */
}, [value]);