|
| 1 | +# Naming Analyzer Skill |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Purpose |
| 6 | + |
| 7 | +Good naming is one of the most important aspects of readable, maintainable code. This skill helps developers: |
| 8 | + |
| 9 | +- **Identify naming issues** in existing code before they become technical debt |
| 10 | +- **Improve code clarity** by replacing vague or misleading names with descriptive ones |
| 11 | +- **Enforce consistency** across a codebase by following language-specific conventions |
| 12 | +- **Reduce cognitive load** for anyone reading or maintaining the code |
| 13 | + |
| 14 | +Poor naming leads to bugs, confusion, and wasted time. This skill acts as an expert code reviewer focused specifically on naming quality. |
| 15 | + |
| 16 | +## When to Use |
| 17 | + |
| 18 | +Use this skill when you want to: |
| 19 | + |
| 20 | +- Review naming conventions in a file, directory, or entire codebase |
| 21 | +- Get suggestions for better variable, function, or class names |
| 22 | +- Check if code follows language-specific naming conventions |
| 23 | +- Identify misleading names that don't match their actual behavior |
| 24 | +- Clean up unclear abbreviations or single-letter variables |
| 25 | +- Standardize boolean naming with proper prefixes |
| 26 | + |
| 27 | +**Trigger phrases:** |
| 28 | + |
| 29 | +- "Analyze the naming in this file" |
| 30 | +- "Suggest better names for my variables" |
| 31 | +- "Check naming conventions in src/" |
| 32 | +- "Review this code for naming issues" |
| 33 | +- "Help me rename these functions" |
| 34 | + |
| 35 | +## How It Works |
| 36 | + |
| 37 | +1. **Analysis Phase**: The skill examines all identifiers in the target code: |
| 38 | + - Variables and constants |
| 39 | + - Functions and methods |
| 40 | + - Classes, interfaces, and types |
| 41 | + - Files and directories |
| 42 | + - Database tables and columns |
| 43 | + - API endpoints |
| 44 | + |
| 45 | +2. **Issue Detection**: Each identifier is evaluated for common problems: |
| 46 | + - Unclear or vague names (`data`, `info`, `temp`, `x`) |
| 47 | + - Abbreviations that obscure meaning (`usrCfg`, `calcTtl`) |
| 48 | + - Inconsistent naming conventions (mixing `camelCase` and `snake_case`) |
| 49 | + - Misleading names (function called `getUser` that also updates data) |
| 50 | + - Names that are too short or too long |
| 51 | + - Single-letter variables outside of loop contexts |
| 52 | + - Missing boolean prefixes (`active` instead of `isActive`) |
| 53 | + |
| 54 | +3. **Convention Checking**: The skill validates against language-specific standards: |
| 55 | + - JavaScript/TypeScript: camelCase for variables/functions, PascalCase for classes |
| 56 | + - Python: snake_case for variables/functions, PascalCase for classes |
| 57 | + - Java: camelCase for variables/methods, PascalCase for classes |
| 58 | + - Go: PascalCase for exported, camelCase for unexported |
| 59 | + |
| 60 | +4. **Report Generation**: A structured report is produced with: |
| 61 | + - Summary statistics (items analyzed, issues found by severity) |
| 62 | + - Critical issues (misleading names that could cause bugs) |
| 63 | + - Major issues (unclear or vague names) |
| 64 | + - Minor issues (convention violations) |
| 65 | + - Specific suggestions with reasoning for each |
| 66 | + |
| 67 | +## Key Features |
| 68 | + |
| 69 | +### Multi-Language Support |
| 70 | + |
| 71 | +Understands naming conventions for JavaScript, TypeScript, Python, Java, Go, and more. Automatically adapts recommendations to the language being analyzed. |
| 72 | + |
| 73 | +### Severity Classification |
| 74 | + |
| 75 | +Issues are categorized by impact: |
| 76 | + |
| 77 | +| Severity | Description | Example | |
| 78 | +|----------|-------------|---------| |
| 79 | +| **Critical** | Misleading names that could cause bugs | `getUser()` that also modifies data | |
| 80 | +| **Major** | Unclear names requiring mental effort to understand | `proc(data)` instead of `processApiResponse(response)` | |
| 81 | +| **Minor** | Convention violations that affect consistency | `API_url` instead of `API_URL` | |
| 82 | + |
| 83 | +### Boolean Naming Guidance |
| 84 | + |
| 85 | +Enforces clear boolean prefixes: |
| 86 | + |
| 87 | +- `is` for state: `isActive`, `isVisible`, `isEnabled` |
| 88 | +- `has` for possession: `hasPermission`, `hasError`, `hasChildren` |
| 89 | +- `can` for ability: `canEdit`, `canDelete`, `canAccess` |
| 90 | +- `should` for decisions: `shouldRender`, `shouldValidate`, `shouldRefresh` |
| 91 | + |
| 92 | +### Magic Number Detection |
| 93 | + |
| 94 | +Identifies unnamed numeric literals and suggests meaningful constant names: |
| 95 | + |
| 96 | +```javascript |
| 97 | +// Before |
| 98 | +if (age > 18) { } |
| 99 | +setTimeout(callback, 3600000); |
| 100 | + |
| 101 | +// After |
| 102 | +const LEGAL_AGE = 18; |
| 103 | +const ONE_HOUR_IN_MS = 60 * 60 * 1000; |
| 104 | + |
| 105 | +if (age > LEGAL_AGE) { } |
| 106 | +setTimeout(callback, ONE_HOUR_IN_MS); |
| 107 | +``` |
| 108 | + |
| 109 | +### Refactoring Support |
| 110 | + |
| 111 | +Can generate refactoring scripts to apply naming changes across the codebase while maintaining git history. |
| 112 | + |
| 113 | +## Usage Examples |
| 114 | + |
| 115 | +**Analyze a single file:** |
| 116 | +``` |
| 117 | +@naming-analyzer UserService.js |
| 118 | +``` |
| 119 | + |
| 120 | +**Analyze an entire directory:** |
| 121 | +``` |
| 122 | +@naming-analyzer src/ |
| 123 | +``` |
| 124 | + |
| 125 | +**Show naming conventions reference:** |
| 126 | +``` |
| 127 | +@naming-analyzer --conventions |
| 128 | +``` |
| 129 | + |
| 130 | +**Analyze and suggest fixes for all issues:** |
| 131 | +``` |
| 132 | +@naming-analyzer --fix-all |
| 133 | +``` |
| 134 | + |
| 135 | +**General invocation:** |
| 136 | +``` |
| 137 | +@naming-analyzer |
| 138 | +``` |
| 139 | +Then provide the code or file path when prompted. |
| 140 | + |
| 141 | +## Output |
| 142 | + |
| 143 | +The skill produces a detailed markdown report containing: |
| 144 | + |
| 145 | +### Summary Section |
| 146 | + |
| 147 | +``` |
| 148 | +## Summary |
| 149 | +- Items analyzed: 156 |
| 150 | +- Issues found: 23 |
| 151 | +- Critical: 5 (misleading names) |
| 152 | +- Major: 12 (unclear/vague) |
| 153 | +- Minor: 6 (convention violations) |
| 154 | +``` |
| 155 | + |
| 156 | +### Issue Details |
| 157 | + |
| 158 | +Each issue includes: |
| 159 | +- **Current**: The existing name |
| 160 | +- **Issue**: Description of the problem |
| 161 | +- **Severity**: Critical, Major, or Minor |
| 162 | +- **Suggestion**: The recommended replacement |
| 163 | +- **Reason**: Why the suggestion is better |
| 164 | + |
| 165 | +### Suggested Renaming |
| 166 | + |
| 167 | +Prioritized list of all recommended changes: |
| 168 | +- High Priority: Misleading or critical issues |
| 169 | +- Medium Priority: Clarity improvements |
| 170 | +- Low Priority: Convention fixes |
| 171 | + |
| 172 | +## Best Practices |
| 173 | + |
| 174 | +### Do |
| 175 | + |
| 176 | +- **Use full words over abbreviations** - `userConfig` not `usrCfg` |
| 177 | +- **Be specific and descriptive** - `emailAddress` not `str` |
| 178 | +- **Follow language conventions** - camelCase in JavaScript, snake_case in Python |
| 179 | +- **Use consistent patterns** - don't mix styles within a file |
| 180 | +- **Make booleans obvious** - `isEnabled`, `hasPermission` |
| 181 | +- **Include units in constants** - `TIMEOUT_MS`, `MAX_SIZE_MB` |
| 182 | + |
| 183 | +### Don't |
| 184 | + |
| 185 | +- **Use single letters** - except in loops (`i`, `j`, `k`) |
| 186 | +- **Use vague names** - avoid `data`, `info`, `temp`, `x`, `result` |
| 187 | +- **Mix naming conventions** - pick one and stick with it |
| 188 | +- **Use misleading names** - name should match behavior exactly |
| 189 | +- **Over-abbreviate** - `calculateTotal` not `calcTtl` |
| 190 | +- **Use Hungarian notation** - not needed in modern typed languages |
| 191 | + |
| 192 | +### Acceptable Abbreviations |
| 193 | + |
| 194 | +Some abbreviations are well-known and acceptable: |
| 195 | +- `html`, `api`, `url`, `id`, `db`, `io`, `ui` |
| 196 | +- `min`, `max`, `src`, `dest`, `config`, `env` |
| 197 | +- `req`, `res` (in HTTP context) |
| 198 | +- `err` (in error handling context) |
| 199 | + |
| 200 | +## Naming Decision Tree |
| 201 | + |
| 202 | +``` |
| 203 | +Is it a boolean? |
| 204 | +├─ Yes → Use is/has/can/should prefix |
| 205 | +└─ No → Is it a function? |
| 206 | + ├─ Yes → Use verb phrase (action) |
| 207 | + └─ No → Is it a class? |
| 208 | + ├─ Yes → Use noun (PascalCase) |
| 209 | + └─ No → Is it a constant? |
| 210 | + ├─ Yes → Use UPPER_SNAKE_CASE |
| 211 | + └─ No → Use descriptive noun (camelCase/snake_case) |
| 212 | +``` |
| 213 | + |
| 214 | +## Notes |
| 215 | + |
| 216 | +- **Context matters**: Loop counters can be `i`, `j` - not every short name is bad |
| 217 | +- **Consistency over perfection**: Being consistent within a project is more important than following every convention perfectly |
| 218 | +- **Refactor as understanding improves**: Names should evolve as you better understand the domain |
| 219 | +- **Use IDE refactoring tools**: When renaming, use your IDE's rename feature to safely update all references |
| 220 | +- **Well-known abbreviations are okay**: `html`, `api`, `url`, `id` are universally understood |
0 commit comments