mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-08-08 00:08:36 +02:00
Luong NGUYENandGitHub
b9a973bf32
Internal accuracy pass against v2.1.220 — no missing upstream features, but broken example code, disagreeing counts, and metadata drift.
Functional fixes: pre-commit.sh now exits 2 so it actually blocks; dependency-check.sh reads file_path from stdin JSON instead of $1; database-mcp.json uses ${DATABASE_URL}; broken fences repaired; three command templates had invalid skill names.
Factual corrections: /fork and /subtask unswapped and /subtask added; /fewer-permission-prompts; permissions.defaultMode; dontAsk/auto unreversed; 31 hook events verified name-by-name; subagent depth 3; skill precedence enterprise > project > personal; /output-style removed not deprecated; permissionDecision gained defer.
Follow-up review fixed defects the pass left behind: zh/vi headers claiming 31 events above 25-name lists, a surviving hardcoded DB credential in the MCP README examples, an unbalanced fence swallowing a metadata footer, and non-canonical tool names. All four translated CATALOG summary tables were recounted so their arithmetic holds.
Full detail in CHANGELOG.md under v2.1.220-r2.
116 lines
4.5 KiB
Markdown
116 lines
4.5 KiB
Markdown
# Clean Code Rules for AI Code Generation
|
|
|
|
These rules guide code generation to produce maintainable, professional-quality code.
|
|
|
|
## Meaningful Names
|
|
- Use intention-revealing names that explain why something exists
|
|
- Avoid disinformation and meaningless distinctions (e.g., `data`, `info`, `manager`)
|
|
- Use pronounceable, searchable names
|
|
- Class names: nouns (e.g., `UserAccount`, `PaymentProcessor`)
|
|
- Method names: verbs (e.g., `calculateTotal`, `sendEmail`)
|
|
- Avoid mental mapping and encodings (Hungarian notation, prefixes)
|
|
|
|
## Functions
|
|
- Keep functions small (< 20 lines ideal)
|
|
- Do one thing only - Single Responsibility Principle
|
|
- One level of abstraction per function
|
|
- Limit arguments: 0-2 ideal, 3 maximum, avoid flag arguments
|
|
- No side effects - function should do what its name says
|
|
- Separate commands (change state) from queries (return info)
|
|
- Prefer exceptions over error codes
|
|
|
|
## Comments
|
|
- Code should be self-explanatory - avoid comments when possible
|
|
- Good comments: legal info, warnings, TODOs, public API documentation
|
|
- Bad comments: redundant, misleading, or explaining bad code
|
|
- Never comment out code - delete it (version control preserves history)
|
|
- If you need a comment, consider refactoring the code instead
|
|
|
|
## Formatting
|
|
- Keep files small and focused
|
|
- Vertical formatting: related concepts close together, blank lines separate concepts
|
|
- Horizontal formatting: limit line length (80-120 characters)
|
|
- Use consistent indentation and team style
|
|
- Group related functions together
|
|
|
|
## Objects and Data Structures
|
|
- Objects: hide data behind abstractions, expose behavior through methods
|
|
- Data structures: expose data, have minimal behavior
|
|
- Law of Demeter: only talk to immediate friends, avoid `a.getB().getC().doSomething()`
|
|
- Don't expose internal structure through getters/setters blindly
|
|
|
|
## Error Handling
|
|
- Use exceptions, not return codes or error flags
|
|
- Write `try-catch-finally` first when code might fail
|
|
- Provide context in exception messages
|
|
- Don't return `null` - return empty collections or use Optional/Maybe
|
|
- Don't pass `null` as arguments
|
|
|
|
## Classes
|
|
- Small classes: measured by responsibilities, not lines
|
|
- Single Responsibility Principle: one reason to change
|
|
- High cohesion: class variables used by many methods
|
|
- Low coupling: minimal dependencies between classes
|
|
- Open/Closed Principle: open for extension, closed for modification
|
|
|
|
## Unit Tests
|
|
- Fast, Independent, Repeatable, Self-validating, Timely (F.I.R.S.T.)
|
|
- One assert per test (or one concept)
|
|
- Test code quality equals production code quality
|
|
- Readable test names that describe what's being tested
|
|
- Arrange-Act-Assert pattern
|
|
|
|
## Code Quality Principles
|
|
- **DRY (Don't Repeat Yourself)**: No duplication
|
|
- **YAGNI (You Aren't Gonna Need It)**: Don't build for hypothetical futures
|
|
- **KISS (Keep It Simple)**: Avoid unnecessary complexity
|
|
- **Boy Scout Rule**: Leave code cleaner than you found it
|
|
|
|
## Code Smells to Avoid
|
|
- Long functions or classes
|
|
- Duplicate code
|
|
- Dead code (unused variables, functions, parameters)
|
|
- Feature envy (method more interested in other class)
|
|
- Inappropriate intimacy (classes knowing too much about each other)
|
|
- Long parameter lists
|
|
- Primitive obsession (overusing primitives instead of small objects)
|
|
- Switch/case statements (consider polymorphism)
|
|
- Temporary fields (class variables only used sometimes)
|
|
|
|
## Concurrency
|
|
- Keep concurrent code separate from other code
|
|
- Limit scope of synchronized/locked data
|
|
- Use thread-safe collections
|
|
- Keep synchronized sections small
|
|
- Know your execution models and primitives
|
|
|
|
## System Design
|
|
- Separate construction from use (dependency injection)
|
|
- Use factories, builders for complex object creation
|
|
- Program to interfaces, not implementations
|
|
- Favor composition over inheritance
|
|
- Apply design patterns when they simplify, not to show off
|
|
|
|
## Refactoring
|
|
- Refactor continuously, not in big batches
|
|
- Always have passing tests before and after
|
|
- Small steps: one change at a time
|
|
- Common refactorings: Extract Method, Rename, Move, Inline
|
|
|
|
## Documentation
|
|
- Self-documenting code > comments > external docs
|
|
- Public APIs need clear documentation
|
|
- Include examples in documentation
|
|
- Keep docs close to code (ideally in code)
|
|
|
|
---
|
|
|
|
**Core Philosophy**: Code is read 10x more than written. Optimize for readability and maintainability, not cleverness.
|
|
|
|
---
|
|
**Last Updated**: August 4, 2026
|
|
**Claude Code Version**: 2.1.220
|
|
**Sources**:
|
|
- https://code.claude.com/docs/en/overview
|
|
**Compatible Models**: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5
|