naming-stuff

Naming Conventions

When in doubt, take time to name things well. It's one of the hardest problems in computer science.

Importance

• Names are a form of documentation that never goes out of date
• Good names reduce cognitive load and make code self-documenting
• Names should reveal intent and provide context
• Time spent on naming is an investment in future understanding

When to Pause and Consider Naming Carefully

The more permanent/harder to change, the more time to spend on naming:

• Creating new models or database tables
• Defining core functions or classes
• Establishing API endpoints or URLs
• Naming background jobs or tasks
• Creating new features or components
• Defining key variables that appear throughout codebase

Notably, don't spend excessive time on naming for simple things that are easy to change.

Naming Signals

Names that accurately describe their contents:

• string-helpers.ts over a generic catch-all name
• user-profile.tsx matching the directory's casing convention
• auth.ts as the final name, not a migration artifact with version suffixes

Names that belong in their context:

• Files matching their directory's established convention (kebab-case, PascalCase, etc.)
• Consistent suffixes where the project uses them (.service.ts, .controller.ts)
• Singular vs plural matching sibling files in the same directory

Names that stay current:

• Rename when the original purpose changes rather than letting name drift from contents
• Remove temporary prefixes/suffixes once migration is complete
• Consolidate when a file has outgrown its original name

When Names Aren't Obvious

When a name for a new file, function, class, etc. isn't immediately obvious:

• Pause and ask what we should name it. It's better to ask than to guess and have to rename later.
• Consider multiple alternatives
• Evaluate options based on:
  • Clarity and intuitiveness
  • Technical accuracy
  • Future flexibility
  • Project context