.cursorrules (deprecated)

1# Clean Code & Refactoring — Cursor Rules
2# Comprehensive rules for writing clean, maintainable, and readable code
3 
4## Project Context
5You are working on a codebase where code quality, readability, and maintainability are
6first-class priorities. Code is read far more often than it is written. Every function,
7class, and module should clearly communicate its intent. The codebase should be easy
8for any developer to understand, modify, and extend.
9 
10## Core Principles
11- Code should read like well-written prose
12- Every function should do one thing and do it well
13- Make the code express the intent — minimize the need for comments
14- Leave the codebase better than you found it (Boy Scout Rule)
15- Optimize for readability first, performance second (unless profiling says otherwise)
16 
17## Naming
18 
19### Rules
20- Names should reveal intent — a reader should know what it does without reading the body
21- Use domain language from the business (Ubiquitous Language from DDD)
22- Be consistent — if you call it `fetch` in one place, don't call it `get` in another
23- Avoid abbreviations unless universally understood (`id`, `url`, `http`)
24- Avoid noise words: `data`, `info`, `temp`, `stuff`, `handler` (when everything is a handler)
25- Name length should correlate with scope size — short names for small scopes, descriptive for large
26 
27### Examples
28```
29// BAD
30const d = new Date();                    // What is d?
31function proc(lst) { ... }              // proc? lst?
32const flag = user.age > 18;             // What flag?
33const temp = calculateTotal(items);     // Why temp?
34 
35// GOOD
36const registrationDate = new Date();
37function filterActiveUsers(users) { ... }
38const isEligibleForAdultContent = user.age > 18;
39const orderTotal = calculateTotal(items);
40```
41 
42### Specific Guidelines
43- **Booleans**: `is`, `has`, `should`, `can` prefix (`isActive`, `hasPermission`)
44- **Functions**: verb + noun (`calculateTotal`, `sendNotification`, `validateEmail`)
45- **Classes**: noun or noun phrase (`UserRepository`, `PaymentProcessor`)
46- **Collections**: plural nouns (`users`, `orderItems`, `pendingTasks`)
47- **Callbacks/handlers**: `on` or `handle` prefix (`onSubmit`, `handleClick`)
48- **Factories**: `create` or `build` prefix (`createUser`, `buildQuery`)
49 
50## Functions
51 
52### Rules
53- Functions should do ONE thing
54- Functions should be short — if you need to scroll, it's too long
55- Aim for 1-3 parameters; 4+ parameters usually means you need an options object
56- No side effects that aren't obvious from the function name
57- Prefer pure functions when possible (same input = same output, no side effects)
58- Functions should operate at one level of abstraction
59 
60### Extract Until You Drop
61```ts
62// BAD — mixed levels of abstraction, doing too many things
63function processOrder(order) {
64  // Validate
65  if (!order.items.length) throw new Error('Empty order');
66  if (!order.user) throw new Error('No user');
67  if (order.items.some(i => i.quantity <= 0)) throw new Error('Invalid quantity');
68 
69  // Calculate
70  let total = 0;
71  for (const item of order.items) {
72    const price = item.price * item.quantity;
73    const discount = item.quantity >= 10 ? price * 0.1 : 0;
74    total += price - discount;
75  }
76  const tax = total * 0.08;
77  total += tax;
78 
79  // Save
80  db.orders.insert({ ...order, total, tax, status: 'pending' });
81  emailService.send(order.user.email, `Order confirmed: $${total}`);
82}
83 
84// GOOD — each function does one thing at one level of abstraction
85function processOrder(order) {
86  validateOrder(order);
87  const { total, tax } = calculateOrderTotal(order.items);
88  const savedOrder = saveOrder(order, total, tax);
89  notifyCustomer(order.user, savedOrder);
90}
91 
92function validateOrder(order) {
93  if (!order.items.length) throw new OrderError('Order must contain at least one item');
94  if (!order.user) throw new OrderError('Order must have an associated user');
95  if (order.items.some(item => item.quantity <= 0)) {
96    throw new OrderError('All items must have a positive quantity');
97  }
98}
99 
100function calculateOrderTotal(items) {
101  const subtotal = items.reduce((sum, item) => sum + calculateItemPrice(item), 0);
102  const tax = subtotal * TAX_RATE;
103  return { total: subtotal + tax, tax };
104}
105 
106function calculateItemPrice(item) {
107  const basePrice = item.price * item.quantity;
108  const discount = item.quantity >= BULK_THRESHOLD ? basePrice * BULK_DISCOUNT_RATE : 0;
109  return basePrice - discount;
110}
111```
112 
113## Conditionals
114 
115### Simplify Complex Conditions
116```ts
117// BAD — what does this check?
118if (user.age >= 18 && user.country === 'US' && !user.isBanned && user.emailVerified) {
119 
120// GOOD — extracted to a named function or variable
121const isEligibleForService = user.age >= 18
122  && user.country === 'US'
123  && !user.isBanned
124  && user.emailVerified;
125 
126if (isEligibleForService) {
127```
128 
129### Use Early Returns (Guard Clauses)
130```ts
131// BAD — deeply nested
132function getDiscount(user) {
133  if (user) {
134    if (user.isPremium) {
135      if (user.yearsActive > 5) {
136        return 0.2;
137      } else {
138        return 0.1;
139      }
140    } else {
141      return 0;
142    }
143  } else {
144    return 0;
145  }
146}
147 
148// GOOD — flat with early returns
149function getDiscount(user) {
150  if (!user) return 0;
151  if (!user.isPremium) return 0;
152  if (user.yearsActive > 5) return 0.2;
153  return 0.1;
154}
155```
156 
157### Avoid Negative Conditions
158```ts
159// BAD
160if (!isNotFound) { ... }
161if (!disableValidation) { ... }
162 
163// GOOD
164if (isFound) { ... }
165if (enableValidation) { ... }
166```
167 
168## Error Handling
169 
170### Rules
171- Don't use exceptions for control flow
172- Throw specific, descriptive error types
173- Handle errors at the appropriate level (don't catch and ignore)
174- Provide context in error messages: what happened, why, and what was attempted
175- Never swallow errors silently — at minimum, log them
176 
177```ts
178// BAD
179try {
180  doSomething();
181} catch (e) {
182  // silently ignored
183}
184 
185// BAD
186throw new Error('error');
187 
188// GOOD
189throw new OrderNotFoundError(`Order ${orderId} not found for user ${userId}`);
190```
191 
192## Comments
193 
194### When Comments Are Needed
195- Explaining WHY, not WHAT (the code shows what; comments explain why)
196- Legal or compliance requirements
197- Warnings about consequences: `// WARNING: This clears the entire cache`
198- TODO/FIXME with ticket numbers: `// TODO(JIRA-123): Replace with batch API`
199- Complex regex or algorithm explanation
200- Public API documentation (JSDoc, docstrings)
201 
202### When to Avoid Comments
203- Explaining WHAT the code does — rename the code instead
204- Commented-out code — delete it, Git has history
205- Journal comments (`// Added by John on 2024-01-15`) — Git has blame
206- Redundant comments: `count++; // increment count`
207- Closing brace comments: `} // end if` — your function is too long
208 
209## Code Smells to Watch For
210- **Long methods** (20+ lines) — break into smaller functions
211- **Long parameter lists** (4+ params) — use an options object or builder
212- **Deep nesting** (3+ levels) — use early returns and extraction
213- **Duplicated code** — extract shared logic into functions/modules
214- **Primitive obsession** — use value objects (`Money`, `EmailAddress`, `DateRange`)
215- **God classes** — split into focused, single-responsibility classes
216- **Feature envy** — a function that uses another class's data more than its own
217- **Magic numbers** — extract to named constants: `const MAX_LOGIN_ATTEMPTS = 5;`
218- **Boolean parameters** — split into two functions or use an enum/options object
219 
220## Refactoring Techniques
221- **Extract function**: Pull a block of code into a named function
222- **Extract variable**: Name a complex expression
223- **Rename**: Make intent clearer (most impactful refactoring)
224- **Inline**: Remove unnecessary indirection
225- **Replace conditional with polymorphism**: Replace switch/if chains with classes
226- **Introduce parameter object**: Group related parameters
227- **Replace magic number with constant**: Name the meaning
228 
229## File Organization
230- Keep files short — if a file has 300+ lines, consider splitting
231- Group related code together
232- Put the public API at the top of the file
233- Private/helper functions below
234- One concept per file (one class, one module, one concern)
235- Consistent ordering within files across the codebase
236 
237## Common Pitfalls
238- Premature abstraction — don't DRY code that happens to look similar but serves different purposes
239- Over-engineering — simple problems need simple solutions (YAGNI)
240- Inconsistent style within a codebase — agree on conventions and follow them
241- Refactoring without tests — always have tests before refactoring
242- Big bang refactors — refactor incrementally, commit often
243- Naming things after their type: `userList`, `nameString` — just use `users`, `name`
244- Mixing abstraction levels in the same function
245- Writing code to impress rather than to communicate
246