clean-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Write concise, technical Dart code with accurate examples
Use functional and declarative programming patterns
Choose descriptive variable names with auxiliary verbs (e.g.,
```
isLoading
```
,
```
hasError
```
)
Keep functions and classes short (< 200 lines, < 10 public methods)
Always use English for code and documentation
Use PascalCase for classes, camelCase for variables and functions, snake_case for files, UPPERCASE for constants
Use arrow syntax for simple methods and expression bodies for one-line getters/setters
Avoid nesting blocks; prefer early checks and returns
Pass and return parameters using RO-RO (Receive Object, Return Object)
Avoid magic numbers; use well-named constants
Follow an 100-character line limit and use trailing commas for better formatting
Follow the lint rules set for this project (
```
all_lint_rules.yaml
```
and
```
analysis_options.yaml
```
)
Strong Typing: Strictly prohibit
```
dynamic
```
. Use
```
Object?
```
or explicit types.
Cascade Pattern: Use cascade notation (
```
..
```
) for cleaner initialization of complex objects where appropriate.
Null Safety: Avoid
```
!
```
null assertion operator unless value is guaranteed non-null by control flow. Prefer pattern matching.
Switch Expressions: Prefer exhaustive
```
switch
```
expressions (no
```
break
```
needed in Dart 3).

300-Line Limit: Strictly flag any file exceeding 300 lines (excluding tests) for decomposition into separate files.
Guard Clauses: Use early returns (e.g.,
```
if (user == null) return;
```
) to reduce indentation.
Meaningful Naming: Use intention-revealing names. Boolean variables MUST use prefixes like
```
is
```
,
```
has
```
,
```
should
```
.
Disposable Lifecycle:
```
TextEditingController
```
,
```
ScrollController
```
,
```
FocusNode
```
,
```
StreamSubscription
```
,
```
AnimationController
```
, etc. MUST be
```
late
```
initialized in
```
initState()
```
and disposed in
```
dispose()
```
. Inline initialization is STRICTLY prohibited to prevent memory leaks and ensure proper lifecycle management.
No Print Statements: STRICTLY prohibit
```
print()
```
. Use
```
AppLogger
```
for all logging.
Localization: Zero hardcoded user-facing strings. Use
```
.arb
```
files and
```
context.l10n
```
.
Reuse: If a widget or code block is used multiple times, extract it into a common widget or utility. Place shared widgets in
```
core/views/widgets
```
.
Library Organization: Group related classes within the same library file. For large libraries, export smaller private libraries from a single top-level library.

300行限制：任何非测试文件代码行数超过300行时必须标记，拆分到不同文件中
卫语句：使用提前返回（例如：
```
if (user == null) return;
```
）减少缩进层级
有意义的命名：使用能体现意图的名称，布尔变量必须使用
```
is
```
、
```
has
```
、
```
should
```
等前缀
可回收资源生命周期：
```
TextEditingController
```
、
```
ScrollController
```
、
```
FocusNode
```
、
```
StreamSubscription
```
、
```
AnimationController
```
等必须在
```
initState()
```
中声明为
```
late
```
初始化，并在
```
dispose()
```
中销毁。严格禁止行内初始化，避免内存泄漏，确保生命周期管理合规
禁止使用Print语句：严格禁止使用
```
print()
```
，所有日志输出使用
```
AppLogger
```
国际化：面向用户的字符串零硬编码，使用
```
.arb
```
文件和
```
context.l10n
```
实现
代码复用：如果某个widget或代码块被多次使用，将其抽取为公共widget或工具函数，公共widget放在
```
core/views/widgets
```
目录下
库组织规范：将相关类放在同一个库文件中，大型库可从单个顶层库导出小型私有库

No Heavy Work in
build()
: Move sorting, filtering, and expensive computations to
```
initState()
```
or
```
didUpdateWidget()
```
. Never compute in every rebuild.
No Nested ScrollViews in the same direction. Use
```
CustomScrollView
```
with Slivers instead.
No Unnecessary Containers: Prefer
```
SizedBox
```
,
```
Padding
```
,
```
DecoratedBox
```
over
```
Container
```
.
Widget Extraction: STRICTLY prohibit private
```
_build*()
```
methods that return widgets. Extract into separate widget classes.

No Redundant Comments: Do not explain WHAT code does. Explain WHY (intent).
Simple & Informative: Comments MUST be concise, informative, and understandable. Avoid "wall of text".
No History Comments: STRICTLY prohibit comments like "fixed X" or "updated Y". Git history is the source of truth.
Follow official documentation for best practices.
Document public classes and methods with clear descriptions, parameters, return values, and a code snippet taken from the codebase
Comment briefly only complex logic and non-obvious code decisions