---
name: naming-conventions-and-style
description: "Use when: improving variable, function, module, or API names; refactoring code for clarity; choosing consistent naming in the dashback backend."
---

# Style

use vs code region markers in code files
use:
// MARK: calls startApi from ./api/index.js
atop important functions

# Naming Conventions — dashback

Apply these conventions when writing or refactoring code in this project.

## Core rules

- Prefer clear domain names over vague generic names.
- Name functions as actions, not nouns.
- Name variables and parameters by what they represent, not by their implementation detail.
- Prefer explicit names over abbreviations unless the abbreviation is standard in the project.
- Keep names consistent across the same subsystem.

## Function naming

- Use verb-based names for routines that do work: `registerRoutes`, `buildApiApp`, `listenOnPort`, `resolveUser`, `validateInput`.
- Use `register`, `build`, `create`, `resolve`, `configure`, `respond`, `validate`, and `render` when the function performs an action.
- Avoid vague names like `load`, `walk`, `handle`, `do`, `process`, `thing`, and `data` when a more specific name is available.
- When a function builds a response object, prefer names like `respondWith...`, `build...Response`, or `create...Payload`.

## Variable naming

- Prefer descriptive nouns or noun phrases: `serverStartedAt`, `startupPromise`, `localPrivateHostPattern`.
- Use boolean names that read like a question when possible: `isAllowedCorsOrigin`, `hasSelectedCompany`, `isDocsRequest`.
- Use `statusCode` instead of `status` when a numeric HTTP status is involved.
- Use `origin` and `request`/`req` precisely; avoid ambiguous names like `body` when `payload` or `userData` is clearer.

## Module naming

- Prefer names that describe the module’s responsibility, not incidental implementation details.
- For API helper modules, names should communicate the response shape or purpose: `meJson` → `respondWithAuthenticatedUser` or `buildCurrentUserResponse`.
- Use consistent file-level naming patterns across the same feature area.

## File naming

- Keep each route responsibility in its own file under `src/api/routes`.
- Use one route module per resource or workflow, not multiple unrelated endpoints in a single file.
- Prefer a single clear file name per route group, for example `auth/me.js`, `company/list.js`, `article/create.js`, or `journal/entries.js`.
- Match the file name to the route’s primary resource or action so the file’s purpose is obvious from the directory tree.
- Avoid generic names like `index.js`, `utils.js`, or `helpers.js` for route modules unless the file is truly the entry point for a module group.
- Keep nested route directories aligned with the URL hierarchy when it improves clarity, e.g. `auth/me.js` for `/auth/me`.

## API and HTTP naming

- Prefer `registerRoutes` over `loadRoutes` when the function actively registers route modules on the app.
- Prefer `buildApiApp` over `createApi` when the function constructs the Express app object.
- Prefer `isAllowedCorsOrigin` over `isAllowedOrigin` for clarity around the specific policy being enforced.
- When a helper adds Google client info to a response, include the domain concept in the name, e.g. `respondWithAuthenticatedUser`.

## Examples from this codebase

Good:
- `registerRoutes`
- `buildApiApp`
- `listenOnPort`
- `startupPromise`
- `serverStartedAt`
- `respondWithAuthenticatedUser`
- `isAllowedCorsOrigin`
- `LOCAL_PRIVATE_HOST_PATTERN`

Avoid:
- `loadRoutes` when the function actually registers route modules
- `walk` in a route auto-loader unless it is explicitly about recursive traversal and the context is clear
- `starting` and `startedAt` when `startupPromise` and `serverStartedAt` are more specific
- `meJson` when the function is really a response builder for authenticated-user payloads
- generic names like `data`, `thing`, `value`, `handle`, `doWork`

## Review checklist

Before finalizing a rename, ask:
- Does the name describe the actual responsibility?
- Does it read clearly in the local code context?
- Is it consistent with neighboring names?
- Is there any ambiguity about the action, domain, or response shape?
- Is it specific enough that a teammate can infer the purpose without reading the implementation?

Use these rules as the default naming standard for backend refactors and new code in the project.