---
description: When naming things - files, functions, urls, etc
alwaysApply: false
version: 1.1.0
---

# 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