90 lines
4.3 KiB
Markdown
90 lines
4.3 KiB
Markdown
---
|
||
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.
|