clean-code-zh

Original：🇨🇳 Chinese

Translated

Follow the principles of Robert C. Martin's *Clean Code* for code review, refactoring, and writing. Covers best practices for naming, functions, comments, and error handling.

1installs

Sourcejackjin1997/clawforge

Added on2026-02-16

NPX Install

npx skill4agent add jackjin1997/clawforge clean-code-zh

SKILL.md Content (Chinese)

View Translation Comparison →

Clean Code

This skill empowers AI Agents to write, review, and refactor code that adheres to the principles of Robert C. Martin (Uncle Bob)'s Clean Code. Its core goal is to improve code readability, maintainability, and long-term productivity.

Core Principles

1. Meaningful Names

Reveal Intention: The name of a variable, function, or class should explain why it exists, what it does, and how it is used.
Avoid Misleading Names: Avoid using words with specific programming meanings (e.g.,
```
accountList
```
unless it is actually a
```
List
```
).
Make Meaningful Distinctions: Avoid vague names like
```
data1
```
,
```
data2
```
, or
```
theMessage
```
.
Use Pronounceable Names: Avoid abbreviations (e.g.,
```
genymdhms
```
->
```
generationTimestamp
```
).
Use Searchable Names: Single-letter variables should only be used inside short loops.

2. Functions

Small: The first rule of functions is to be small. The second rule is to be even smaller.
Do One Thing: A function should do one thing, do it well, and only do that one thing.
One Level of Abstraction per Function: Ensure all statements within a function are at the same level of abstraction.
Function Arguments: The ideal number of arguments is zero, followed by one, then two. Avoid three or more arguments as much as possible.
No Side Effects: Functions should not secretly modify global variables or object states.
Separate Commands from Queries: A function should either perform an action or answer a question, not both.

3. Comments

Comments Cannot Rescue Bad Code: Code should be self-explanatory. If comments are needed, first consider whether refactoring can eliminate the need for them.
Good Comments: Legal information, explanations of intent, warnings of consequences, TODO comments.
Bad Comments: Rambling, redundant comments, misleading comments, log-style comments, signature comments, meaningless comments.

4. Formatting

Vertical Distance: Closely related concepts should be vertically close to each other.
Horizontal Formatting: Code lines should not be too wide (recommended limit of 100-120 characters).
Team Rules: Always follow the formatting conventions agreed upon by the team.

5. Error Handling

Use Exceptions Rather Than Return Codes: Return codes can lead to messy caller logic.
Write Try-Catch-Finally First: This helps define the scope of the program.
Don’t Return Null: Return an empty collection or throw an exception to avoid null checks everywhere.
Don’t Pass Null: Unless explicitly required by the API, never pass null to a function.

6. Classes

Single Responsibility Principle (SRP): A class should have only one reason to change.
Cohesion: A class should have a small number of instance variables, and methods should operate on these variables.
Organize for Change: Classes should be open for extension but closed for modification (OCP).

When to Use

Writing New Features: Ensure the initial implementation meets clean code standards.
Code Review: Identify patterns that violate clean code principles.
Technical Debt Refactoring: Convert "it works" code into professional-grade code.
API Design: Create intuitive and self-explanatory interfaces.

Review Checklist

Does the name express its intention?
Is the function longer than 20 lines?
Does the function mix multiple levels of abstraction?
Can a comment be eliminated by renaming a variable?
Is exception handling used instead of if/else return error codes?
Is the class too large (violates SRP)?