Files

seb 1149ffddcb u

2026-10-11 12:58:15 +02:00

name, description

name	description
naming-conventions-and-style	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.

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.

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.

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.

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.

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.

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.

Good:

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

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.