# Clean Code — Naming, Functions, and Readability That Scales

## Why Clean Code Matters

Code is read far more often than it's written. Clean code reduces cognitive load, speeds onboarding, and makes changes safer.

## Naming Conventions

**Reveal intent:**
```javascript
// Bad
const d = 86400;
// Good
const secondsPerDay = 86400;
```

**Avoid disinformation:** Don't use `accountList` if it's not a List. Use `accounts` or `accountGroup`.

**Use pronounceable names:**
```javascript
// Bad
const genymdhms = ...;
// Good
const generationTimestamp = ...;
```

**Use searchable names:** `MAX_ITEMS` is better than `7` scattered in code.

## Function Design

### Small and Focused

Each function should do one thing. If you can name it with "and," it does too much:

```javascript
// Bad: does validation AND save AND send email
function processUser(data) { ... }

// Good: single responsibility
function validateUser(data) { ... }
function saveUser(user) { ... }
function notifyUser(user) { ... }
```

### Few Arguments

Ideal: 0–2 arguments. 3+ suggests the function needs a parameter object:

```javascript
// Bad
function createUser(name, email, age, country, role) { ... }

// Good
function createUser(userData) { ... }
```

### No Side Effects

Functions should not surprise callers. Hidden changes cause bugs:

```javascript
// Bad: modifies global, changes session
function checkPassword(user, password) {
  if (valid) session.authenticated = true;  // side effect!
  return valid;
}
```

## Avoiding Magic Numbers

Replace unexplained literals with named constants:

```javascript
// Bad
if (status === 3) { ... }
setTimeout(callback, 86400000);

// Good
const ORDER_STATUS_SHIPPED = 3;
const MS_PER_DAY = 24 * 60 * 60 * 1000;
if (status === ORDER_STATUS_SHIPPED) { ... }
setTimeout(callback, MS_PER_DAY);
```

## DRY and YAGNI

- **DRY (Don't Repeat Yourself):** Extract duplication into functions, constants, or modules.
- **YAGNI (You Ain't Gonna Need It):** Don't add code for hypothetical future requirements.

Balance: abstract when you see the *third* repetition, not the second.

## Comments vs Self-Documenting Code

Prefer clear code over comments:

```javascript
// Bad
// Check if user is old enough
if (u.a > 17) { ... }

// Good
const isAdult = user.age >= 18;
if (isAdult) { ... }
```

**Good comments:** explain *why*, not *what*. Legal requirements, workarounds, non-obvious algorithms.

## Code Smells

| Smell | Fix |
|-------|-----|
| Long function | Extract smaller functions |
| Long parameter list | Use object parameter |
| Duplicate code | Extract and reuse |
| Deep nesting | Early returns, extract functions |
| Unclear names | Rename for clarity |

## Before/After Refactoring

**Before:**
```javascript
function calc(d, t) {
  if (t === 0) return 0;
  return d / t;
}
```

**After:**
```javascript
function calculateSpeed(distanceInMeters, timeInSeconds) {
  if (timeInSeconds === 0) return 0;
  return distanceInMeters / timeInSeconds;
}
```

Readability improved; intent is obvious.