general-coding-guidelines（通用编码指南）

General Coding Guidelines

These are general guidelines that apply to all code. They need to be followed when creating and code and reviewed code is expected to follow these guidelines.

1) Coding Principles

A) Correctness > Clarity > Consistency > Performance > Cleverness

• Do not introduce clever abstractions.
• Prefer boring, standard solutions that match the repo style.

B) DRY (practical)

• Avoid repeating logic that might change.
• Avoid multiple large chunks of code in a single function.
• Extract shared logic into:

1. private method (same class) 2. dedicated service (bounded context) 3. helper (only if truly global and reusable)

C) SOLID (practical)

• Classes/functions should have one reason to change.
• Prefer composition over inheritance.
• Depend on interfaces/contracts where it improves testability and flexibility.

2) Variables & Functions (readability rules)

• Prefer clear naming over fewer variables.
• Inline values only if it improves clarity and avoids noise.
• Extract a function when:

- a block repeats, - a block is hard to name inline, - it improves testability.

3) Comments Policy

• Avoid inline comments.
• Prefer descriptive names and small functions.
• Allowed comments:

- Non-obvious constraints - Workarounds for external bugs - “Why” something is done (not “what”)

4) Database & Migrations Safety (language/framework-agnostic)

• Prefer additive, backwards-compatible schema changes when possible.
• Avoid destructive changes unless explicitly required.
• For destructive changes:

- Call out irreversibility and data risk. - Provide a safe plan (two-step deploy or backfill approach).

• For large tables:

- Avoid long-running locks where possible. - Prefer online/low-lock patterns (nullable column → backfill in batches → add constraints).

• Always consider rollback behavior:

- Implement a rollback when feasible. - If rollback is unsafe, explicitly document it.

• Never drop/rename in a way that breaks running code during rolling deploys unless coordinated.

5) Performance & Query Hygiene (framework-agnostic)

• Default to clarity, but avoid obvious performance pitfalls.
• When touching query/data-heavy code:

- Avoid N+1-style behavior (load in batches, use joins/eager loading equivalents). - Avoid fetching full records when only checking existence/count. - Paginate/limit large result sets. - Select only needed fields for large reads.

• Add indexes for frequently filtered/sorted columns where appropriate.
• Mention any performance-related changes in Notes/Risks.

6) Git / Commits

• Do not commit changes unless otherwise instructed.
• The user handles commits.

7) Linters / Static Analysis

• Do not run linters (eslint/phpstan/etc.) unless explicitly requested.
• However, write code that would pass typical linters.

8) Global Helpers

• Only create global helpers when reuse is likely across the codebase.
• If you add global helpers, document them in the project's README or AGENTS.md.

9) Avoid code smells

Watch for and avoid these anti-patterns:

a) Long Functions

// ❌ BAD: Function > 50 lines
function processMarketData() {
  // 100 lines of code
}

// ✅ GOOD: Split into smaller functions
function processMarketData() {
  const validated = validateData()
  const transformed = transformData(validated)
  return saveData(transformed)
}

b) Deep Nesting

// ❌ BAD: 3+ levels of nesting
if (user) {
  if (user.isAdmin) {
    if (market) {
      if (market.isActive) {
        if (hasPermission) {
          // Do something
        }
      }
    }
  }
}

// ✅ GOOD: Early returns
if (!user) return
if (!user.isAdmin) return
if (!market) return
if (!market.isActive) return
if (!hasPermission) return

// Do something

c) Magic Numbers

// ❌ BAD: Unexplained numbers
if ($retryCount > 3) { }
set_time_limit(500);

// ✅ GOOD: Named constants
$MAX_RETRIES = 3;
$DEBOUNCE_DELAY_MS = 500;

if ($retryCount > $MAX_RETRIES) { }
set_time_limit($DEBOUNCE_DELAY_MS);

10).env files

.env.example files are a great way to document the environment variables required for a project. Populate them with happy defaults. if an environment variables should always be changed by the user, add it to the.env.example file without a value. For example:

ADMIN_USERNAME=admin
ADMIN_PASSWORD=