# Naming Analyzer Skill

A skill for Claude Code that analyzes code naming conventions and suggests better variable, function, class, and other identifier names based on context and industry standards.

## Purpose

Good naming is one of the most important aspects of readable, maintainable code. This skill helps developers:

- **Identify naming issues** in existing code before they become technical debt
- **Improve code clarity** by replacing vague or misleading names with descriptive ones
- **Enforce consistency** across a codebase by following language-specific conventions
- **Reduce cognitive load** for anyone reading or maintaining the code

Poor naming leads to bugs, confusion, and wasted time. This skill acts as an expert code reviewer focused specifically on naming quality.

## When to Use

Use this skill when you want to:

- Review naming conventions in a file, directory, or entire codebase
- Get suggestions for better variable, function, or class names
- Check if code follows language-specific naming conventions
- Identify misleading names that don't match their actual behavior
- Clean up unclear abbreviations or single-letter variables
- Standardize boolean naming with proper prefixes

**Trigger phrases:**

- "Analyze the naming in this file"
- "Suggest better names for my variables"
- "Check naming conventions in src/"
- "Review this code for naming issues"
- "Help me rename these functions"

## How It Works

1. **Analysis Phase**: The skill examines all identifiers in the target code:
   - Variables and constants
   - Functions and methods
   - Classes, interfaces, and types
   - Files and directories
   - Database tables and columns
   - API endpoints

2. **Issue Detection**: Each identifier is evaluated for common problems:
   - Unclear or vague names (`data`, `info`, `temp`, `x`)
   - Abbreviations that obscure meaning (`usrCfg`, `calcTtl`)
   - Inconsistent naming conventions (mixing `camelCase` and `snake_case`)
   - Misleading names (function called `getUser` that also updates data)
   - Names that are too short or too long
   - Single-letter variables outside of loop contexts
   - Missing boolean prefixes (`active` instead of `isActive`)

3. **Convention Checking**: The skill validates against language-specific standards:
   - JavaScript/TypeScript: camelCase for variables/functions, PascalCase for classes
   - Python: snake_case for variables/functions, PascalCase for classes
   - Java: camelCase for variables/methods, PascalCase for classes
   - Go: PascalCase for exported, camelCase for unexported

4. **Report Generation**: A structured report is produced with:
   - Summary statistics (items analyzed, issues found by severity)
   - Critical issues (misleading names that could cause bugs)
   - Major issues (unclear or vague names)
   - Minor issues (convention violations)
   - Specific suggestions with reasoning for each

## Key Features

### Multi-Language Support

Understands naming conventions for JavaScript, TypeScript, Python, Java, Go, and more. Automatically adapts recommendations to the language being analyzed.

### Severity Classification

Issues are categorized by impact:

| Severity | Description | Example |
|----------|-------------|---------|
| **Critical** | Misleading names that could cause bugs | `getUser()` that also modifies data |
| **Major** | Unclear names requiring mental effort to understand | `proc(data)` instead of `processApiResponse(response)` |
| **Minor** | Convention violations that affect consistency | `API_url` instead of `API_URL` |

### Boolean Naming Guidance

Enforces clear boolean prefixes:

- `is` for state: `isActive`, `isVisible`, `isEnabled`
- `has` for possession: `hasPermission`, `hasError`, `hasChildren`
- `can` for ability: `canEdit`, `canDelete`, `canAccess`
- `should` for decisions: `shouldRender`, `shouldValidate`, `shouldRefresh`

### Magic Number Detection

Identifies unnamed numeric literals and suggests meaningful constant names:

```javascript
// Before
if (age > 18) { }
setTimeout(callback, 3600000);

// After
const LEGAL_AGE = 18;
const ONE_HOUR_IN_MS = 60 * 60 * 1000;

if (age > LEGAL_AGE) { }
setTimeout(callback, ONE_HOUR_IN_MS);
```

### Refactoring Support

Can generate refactoring scripts to apply naming changes across the codebase while maintaining git history.

## Usage Examples

**Analyze a single file:**
```
@naming-analyzer UserService.js
```

**Analyze an entire directory:**
```
@naming-analyzer src/
```

**Show naming conventions reference:**
```
@naming-analyzer --conventions
```

**Analyze and suggest fixes for all issues:**
```
@naming-analyzer --fix-all
```

**General invocation:**
```
@naming-analyzer
```
Then provide the code or file path when prompted.

## Output

The skill produces a detailed markdown report containing:

### Summary Section

```
## Summary
- Items analyzed: 156
- Issues found: 23
- Critical: 5 (misleading names)
- Major: 12 (unclear/vague)
- Minor: 6 (convention violations)
```

### Issue Details

Each issue includes:
- **Current**: The existing name
- **Issue**: Description of the problem
- **Severity**: Critical, Major, or Minor
- **Suggestion**: The recommended replacement
- **Reason**: Why the suggestion is better

### Suggested Renaming

Prioritized list of all recommended changes:
- High Priority: Misleading or critical issues
- Medium Priority: Clarity improvements
- Low Priority: Convention fixes

## Best Practices

### Do

- **Use full words over abbreviations** - `userConfig` not `usrCfg`
- **Be specific and descriptive** - `emailAddress` not `str`
- **Follow language conventions** - camelCase in JavaScript, snake_case in Python
- **Use consistent patterns** - don't mix styles within a file
- **Make booleans obvious** - `isEnabled`, `hasPermission`
- **Include units in constants** - `TIMEOUT_MS`, `MAX_SIZE_MB`

### Don't

- **Use single letters** - except in loops (`i`, `j`, `k`)
- **Use vague names** - avoid `data`, `info`, `temp`, `x`, `result`
- **Mix naming conventions** - pick one and stick with it
- **Use misleading names** - name should match behavior exactly
- **Over-abbreviate** - `calculateTotal` not `calcTtl`
- **Use Hungarian notation** - not needed in modern typed languages

### Acceptable Abbreviations

Some abbreviations are well-known and acceptable:
- `html`, `api`, `url`, `id`, `db`, `io`, `ui`
- `min`, `max`, `src`, `dest`, `config`, `env`
- `req`, `res` (in HTTP context)
- `err` (in error handling context)

## Naming Decision Tree

```
Is it a boolean?
├─ Yes → Use is/has/can/should prefix
└─ No → Is it a function?
    ├─ Yes → Use verb phrase (action)
    └─ No → Is it a class?
        ├─ Yes → Use noun (PascalCase)
        └─ No → Is it a constant?
            ├─ Yes → Use UPPER_SNAKE_CASE
            └─ No → Use descriptive noun (camelCase/snake_case)
```

## Notes

- **Context matters**: Loop counters can be `i`, `j` - not every short name is bad
- **Consistency over perfection**: Being consistent within a project is more important than following every convention perfectly
- **Refactor as understanding improves**: Names should evolve as you better understand the domain
- **Use IDE refactoring tools**: When renaming, use your IDE's rename feature to safely update all references
- **Well-known abbreviations are okay**: `html`, `api`, `url`, `id` are universally understood