70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
---
|
|
name: clean-code
|
|
description: Apply clean code principles, SOLID, and DRY practices. Use when writing, reviewing, or refactoring application code.
|
|
category: code
|
|
impact: medium
|
|
---
|
|
|
|
# Clean Code Guidelines
|
|
|
|
## 🎯 Purpose
|
|
Provide strict boundaries for coding style ensuring clean, maintainable, single-responsibility, and readable architecture.
|
|
|
|
**🚨 CRITICAL: If the task involves deep refactoring, architectural reviews, or you need to understand the 'Newspaper Readability', 'Declarative Layers' or formatting nuances, YOU MUST use the `read_file` tool to read `.ai/skills/clean-code/REFERENCE.md` BEFORE generating any code.**
|
|
|
|
## 🚨 Prohibitions (Thou Shalt Not)
|
|
|
|
- **NEVER write functions that do more than one thing.** If you can extract a meaningful function, do it.
|
|
- **NEVER mix levels of abstraction in one function.** High-level orchestration and low-level math/DB calls do not belong together (SLAB principle).
|
|
- **NEVER use flag arguments** (e.g., `delete(file, true)`). Split into two functions.
|
|
- **NEVER write functions with side effects** that don't match the name.
|
|
- **NEVER leave commented-out code or TODOs.** Delete them.
|
|
- **NEVER write comments that explain "what" the code does.** Comments are ONLY for explaining "why" (bugs, quirks, external constraints).
|
|
- **NEVER use unbraced `if`, `for`, or `while` statements.** Always use `{}` even for single lines.
|
|
|
|
## Workflows (Quality Checklist)
|
|
|
|
When returning code, actively verify:
|
|
1. **Naming:** Does the name reveal intent (`daysSinceLastPayment` vs `d`), is it searchable, and does it use a consistent vocabulary?
|
|
2. **Abstractions (SLAB):** Does the top-level function read declaratively (describing intent without loops or string parsing)? Are the mechanics hidden in bottom-layer imperative functions?
|
|
3. **Guard Clauses:** Are error cases and edge conditions returned early at the top of the function to avoid deep nesting?
|
|
4. **Formatting:** Are related declarations close together? Is there no "optical illusion" (like an unbraced `if` followed by misleading indentation)?
|
|
|
|
## ✅ / ❌ Examples
|
|
|
|
### Single Level of Abstraction (SLAB)
|
|
```typescript
|
|
// ❌ FORBIDDEN: Mixed levels of high-level policy and low-level mutation
|
|
function processOrder(order: Order): void {
|
|
if (order.total < 100) { // high-level policy
|
|
const discount = order.total * 0.1; // low-level calc
|
|
order.total -= discount; // mutation
|
|
}
|
|
}
|
|
|
|
// ✅ REQUIRED: One level of abstraction per function
|
|
function processOrder(order: Order): void {
|
|
const validated = validateOrder(order);
|
|
const discounted = applyDiscount(validated);
|
|
saveOrder(discounted);
|
|
}
|
|
```
|
|
|
|
### Guard Clauses
|
|
```typescript
|
|
// ❌ FORBIDDEN: Deeply nested happy path
|
|
function handleUser(user: User): void {
|
|
if (user != null) {
|
|
if (user.isActive) {
|
|
process(user);
|
|
}
|
|
}
|
|
}
|
|
|
|
// ✅ REQUIRED: Return early
|
|
function handleUser(user: User): void {
|
|
if (user == null || !user.isActive) return;
|
|
process(user);
|
|
}
|
|
```
|