clean-code-zh

Clean Code

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

Core Principles

1. Meaningful Names

• Intention-Revealing: The name of a variable, function, or class should explain its reason for existence, what it does, and how it is used.
• Avoid Disinformation: Avoid using words with specific programming meanings (such as accountList unless it really is List）。
• Make Meaningful Distinctions: Avoid using data1, data2 or theMessage such vague names.
• Use Pronounceable Names: Avoid using abbreviations (such as genymdhms -> generationTimestamp）。
• Use Searchable Names: Single-letter variables should be limited to use inside short loops.

2. Functions

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

3. Comments

• Comments Cannot Beautify Bad Code: Code should be self-explanatory. If a comment is needed, first consider whether the comment can be eliminated through refactoring.
• Good Comments: Legal information, explanation of intent, warning of consequences, TODO comments.
• Bad Comments: Mumbling, redundant comments, misleading comments, mandated comments, journal comments, noise comments.

4. Formatting

• Vertical Distance: Concepts that are closely related should be kept vertically close to each other.
• Horizontal Formatting: Lines of code should not be too wide (it is recommended to limit them to within 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 lead to confusing logic for the caller.
• Write Try-Catch-Finally Statements 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 the API explicitly requires it, passing null to a function is prohibited.

6. Classes

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

When to Use

• Writing new features: Ensure the initial implementation meets clean standards.
• Code Review: Identify patterns that violate clean principles.
• Technical debt refactoring: Transform "it just needs to work" code into professional-grade code.
• API design: Create intuitive and self-explanatory interfaces.

Review Checklist

1. Do the names express intent?
2. Do the functions exceed 20 lines?
3. Do the functions mix multiple levels of abstraction?
4. Can a certain comment be eliminated by renaming a variable?
5. Is exception handling used instead of if/else returning error codes?
6. Is the class too large (violating SRP)?