Back to Details

coding-guidelines

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Coding Guidelines

编码指南

Overview

概述

Apply these rules to produce predictable, debuggable code that can be safely rewritten by future LLMs. These coding principles are mandatory! Assume all code will be written and maintained by LLMs, not humans. Optimize for model reasoning, regeneration, and debugging — not human aesthetics.
应用这些规则来生成可预测、可调试的代码，这类代码可以被后续的LLM安全重写。这些编码原则是强制性的！ 假设所有代码都将由LLM而非人类编写和维护，优化方向是适配模型推理、重生成和调试，而非符合人类审美。

Principles

原则

1. Structure

1. 结构

  • Use a consistent, predictable project layout.
  • Group code by feature or screen; keep shared utilities minimal.
  • Create simple, obvious entry points.
  • Identify shared structure before scaffolding multiple files.
  • Use framework-native composition patterns for shared elements.
  • Treat duplication that needs the same fix in multiple places as a code smell.
  • 采用一致、可预测的项目布局。
  • 按功能或页面分组代码；尽量减少共享工具类。
  • 设置简单、清晰的入口点。
  • 在搭建多个文件前先确定共享结构。
  • 共享元素采用框架原生的组合模式。
  • 需要在多处进行相同修复的重复代码属于代码坏味道。

2. Architecture

2. 架构

  • Prefer flat, explicit code over abstractions or deep hierarchies.
  • Avoid clever patterns, metaprogramming, and unnecessary indirection.
  • Minimize coupling so files can be safely regenerated.
  • 相较于抽象或深层层级结构，优先选择扁平、明确的代码。
  • 避免花哨的模式、元编程和不必要的间接调用。
  • 最小化耦合，确保文件可以被安全重生成。

3. Functions and Modules

3. 函数和模块

  • Keep control flow linear and simple.
  • Use small-to-medium functions; avoid deeply nested logic.
  • Pass state explicitly; avoid globals.
  • 保持控制流线性、简单。
  • 采用中小规模的函数；避免深度嵌套的逻辑。
  • 显式传递状态；避免使用全局变量。

4. Naming and Comments

4. 命名和注释

  • Use descriptive-but-simple names.
  • Comment only to note invariants, assumptions, or external requirements.
  • 使用描述性强且简洁的名称。
  • 仅在标注不变量、假设或外部要求时才添加注释。

5. Logging and Errors

5. 日志和错误

  • Emit detailed, structured logs at key boundaries.
  • Make errors explicit and informative.
  • 在关键边界输出详细的结构化日志。
  • 错误要明确且信息丰富。

6. Regenerability

6. 可重生成性

  • Write code so any file or module can be rewritten from scratch without breaking the system.
  • Prefer clear, declarative configuration (JSON/YAML/etc.).
  • 编写代码时要保证任意文件或模块可以被完全重写，且不会破坏系统运行。
  • 优先选择清晰的声明式配置（JSON/YAML等）。

7. Platform Use

7. 平台使用

  • Use platform conventions directly and simply without over-abstracting.
  • 直接、简洁地遵循平台规范，不要过度抽象。

8. Modifications

8. 代码修改

  • When extending or refactoring, follow existing patterns.
  • Prefer full-file rewrites over micro-edits unless instructed otherwise.
  • 扩展或重构代码时，遵循现有模式。
  • 除非另有指示，优先选择全文件重写而非微修改。

9. Quality

9. 质量

  • Favor deterministic, testable behavior.
  • Keep tests simple and focused on verifying observable behavior.
  • 偏好确定性、可测试的行为。
  • 保持测试简单，聚焦于验证可观测的行为。

Your goal:

你的目标：

Produce code that is predictable, debuggable, and easy for future LLMs to rewrite or extend.
生成可预测、可调试，且便于后续LLM重写或扩展的代码。