Naming in backend systems: code, database, API and events Basic

This cluster answers: how to name code, tables, endpoints and events so that the next reader does not have to guess, and which parts are technical standards versus team conventions.

The problem

A PR has a function processData(data, flag), a table tblOrderInfo, a column CreatedDate, a topic order-topic. The code works, but the reviewer has to open three files to learn what flag means and which time zone that column stores.

Code is read far more often than it is written. Names are also the language of the domain: if the business says “cancelled order”, the code says deleted, the database says status = 9 and the event says OrderRemoved, every meeting needs an interpreter. See Bounded Context.

Reading order

Loading diagram…

In this cluster

Part	Answers the question
Core rules	What are the six general rules? How do TypeScript and NestJS name files, classes, DTOs?
PostgreSQL	Why snake_case? The 63-byte limit? What are the default constraint/index names?
API, events, env	How do you name REST paths, JSON fields, events, Kafka topics, env vars, git branches?
Common mistakes	Which names cause real bugs, and what is the review checklist?

Decision table: which casing where

Where	Convention	Example	Basis
Variables, functions, methods, properties (TS)	lowerCamelCase	orderTotal, findOrderById	Google TS Style Guide
Classes, interfaces, types, enums, decorators	UpperCamelCase	OrderService, PaymentStatus	Google TS Style Guide
Module-level constants, enum values	CONSTANT_CASE	MAX_RETRY_ATTEMPTS	Google TS Style Guide
NestJS files	kebab-case.<kind>.ts	orders.controller.ts, create-order.dto.ts	Examples in the NestJS docs
Tables, columns, constraints, indexes (PostgreSQL)	snake_case, only a-z 0-9 _	order_items, created_at	PostgreSQL case folding
REST path segments	kebab-case, plural nouns	/payment-methods/{id}	Microsoft REST Guidelines
JSON fields	camelCase	{ "orderId": "..." }	Microsoft REST Guidelines
Event names	UpperCamelCase, past tense	OrderPaid	Team convention
Kafka topics	lowercase, dots for hierarchy	billing.order-paid.v1	Team convention, characters per Kafka
Env vars	UPPER_SNAKE_CASE, with a prefix	PAYMENT_API_TIMEOUT_MS	POSIX
Git branches	type/ticket-description	fix/PAY-142-refund-rounding	Team convention

Where there is a standard or technical constraint, follow it. Where it is a team convention, choose once, write it in the README, and let a linter check it.

When to apply, and the exceptions

Apply immediately to all new code, tables, endpoints and topics. Reasonable exceptions:

• A codebase with a consistent older convention: consistency matters more than being “right”. Do not mix IFoo and Foo in one repo; change the whole repo at once or leave it.
• Published contracts (endpoints, JSON fields, topics, columns other teams use): renaming is a breaking change and needs a new version or a parallel run.
• Names dictated by outsiders (partner webhooks, HTTP headers, JWT sub and exp claims): keep them at the boundary and map to your own names right after.
• The domain already has a term: if the business calls it settlement, do not rename it payout to make it “easier to understand”.

Summary

Key takeaways

• Names are read more than written; optimize for the next reader and use the language of the domain.
• One word per concept; booleans are non-negated questions; numbers carry units.
• TypeScript follows the Google TS Style Guide: no I prefix, no _ for private, abbreviations treated as words.
• PostgreSQL: only a-z 0-9 _, at most 63 bytes, name constraints and indexes explicitly.
• APIs: plural nouns, one casing style for paths and JSON; events in past tense, topics with domain and version.
• Consistency beats “right”; rename published contracts via migration, not via refactor.

Next: Core rules.