Naming
Names from the domain, used consistently.
Name things with domain words, and use the same word for the same thing everywhere.
A codebase is a vocabulary. If "request", "job", "query" and "generation" all mean the same thing, every reader has to learn four words for one idea, and will suspect they mean four different things.
Build a small glossary
Keep a short list of the core nouns of your system, with one-line definitions, in the README or at the top of the main module. For a text-generation server it might be:
| Word | Means | Never call it |
|---|---|---|
Request | what a client submitted: a prompt and its limits | job, query, task |
Sequence | an admitted request while it's being generated | request (it has state now), generation, stream |
Batch | the sequences run together in one forward pass | group, bundle, micro-batch |
Step | one forward pass that adds one token to each sequence | iteration, tick, round |
Worker | a process that owns one GPU | replica, node, executor |
Then hold the line in review. New words need a reason.
Guidelines
Functions are verbs, values are nouns
admit(request), retire_finished(), detokenize(tokens). Booleans read as questions: is_finished, has_free_slot, can_accept().
Say what it is, not what type it is
seq_dict = {}
id_list = []
data = model.forward(input_map)
tmp = tokenizer.decode(data)running_by_id = {}
waiting_ids = []
logits = model.forward(batch)
text = tokenizer.decode(token_ids)Units in the name when they aren't obvious
timeout_s, kv_cache_bytes, latency_ms, max_new_tokens. This prevents a whole class of bugs that types don't catch.
Length matches scope
A loop index over three lines can be i. A module-level constant read in five files needs a full name. Avoid abbreviations except universal ones (id, url, gpu, kv).
Private means private
A leading underscore says "not part of this module's interface". Use it for that, and don't import _names from other modules. If another module needs it, it's public; drop the underscore.
No framework words for domain things
Manager, Handler, Processor and Helper say almost nothing. Prefer what the thing actually does: Scheduler, BlockAllocator, Detokenizer.