NAMING

How does a name in the code state what it names, in every language?

Binds: code, code::swift, code::python

This page states the naming rules that Swift, Python and TypeScript share. PYTHON.md and SWIFT.md state the case of a name in each language. PYTHON_TESTING.md and SWIFT_TESTING.md state the form of a test name.

A name states its intent

Chapter 2 of Clean Code by Robert C. Martin sets these rules, and section 3.16 of the Google Python Style Guide agrees with them, at https://google.github.io/styleguide/pyguide.html#s3.16-naming:

• A name states its intent. A reader needs no comment to know what it holds.
• A name carries no abbreviation that a reader outside this repository must guess. A name deletes no letters inside a word.
• A name carries no encoding of its type, such as id_to_name_dict.
• One concept takes one word across the codebase.
• A longer name that leaves no doubt wins over a short one.

A name states what a thing is, or the interface that it offers

A name names no caller, no use and no role. A new caller then renames nothing. A package that holds an MCP server is a server, whichever client starts it. A word for an activity of one caller fails this rule, and so does a word for a role.

A language page can define a suffix for the role of a type in its layer. Such a role is part of what the type is. SWIFT_LAYERS.md defines the suffixes of Swift.

Each name passes or fails on its own

A reviewer reads one name at a time. So each rule below names a form that one name can fail.

• A function name says what the function does. A noun phrase names a function that hands back a thing that already exists, as it is or after a trivial conversion. A function that works its answer out names that work with a verb, such as relay_review_output. A bare participle or adjective names no work. relayed, refused, staged and fresh fail.

• A function that guards against a fault names the fault that it detects. detect_several_changes passes. A name of the verdict or of the message that the function hands back fails, such as refusal_reason.

• A name does not repeat the module or the type that holds it. The qualified name reads as one phrase, such as pre_push_gate.detect_several_changes. push.detect_several_changes_in_push fails.

• A function that loops until an event names each event that ends the loop. The reader of relay_review_output_until_exit knows that the call blocks until the review exits. relay_agy_events_until_result_or_close names both of its ends. relay_review_output fails for a function that loops.

• A context manager names the state that holds inside its with. It reads after with, so a participle fits there: with stop_signal_handling_deferred():. A context manager that yields a resource names that resource, such as unlinked_temporary_file.

• A name shows what a call costs. A function that reaches the network, a model provider or a long-running process says so with its verb, such as fetch_ or run_. A local git read is no such cost. A function that reads local state alone carries no such verb, and a loop can call it. fetch_git_remote passes, and so does find_newest_ancestor_on_git_remote. A find_ name that also fetches fails.

• A name states its domain where the module does not. In a review tool, a remote can be a reviewer or a model provider. git_remote passes, and a bare remote fails in a module that does not state Git.

• A constant names what it holds. A compiled pattern names what it matches, such as HUNK_HEADER. A message names its text, such as BUSY_MESSAGE. A number names its unit or its limit, such as WAIT_SECONDS or REPLY_BYTE_LIMIT. HUNK, BUSY and WAIT fail.

• A name of one word is a noun that names one kind of thing. Receipt passes. A one-word name that is a verb, a participle or an adjective fails, because it names no thing.

• A boolean name reads as a question that true or false answers. branch_contains_base and is_ancestor pass. base and check fail. The rule names a value or a check with no effect. A function that acts and answers whether the act happened takes the verb of the act, such as threading.Lock.acquire of the Python standard library.

• A name that a docstring explains is too short. A reader of the call site sees the name, and not the docstring.

• A type that keeps the method names of a standard type, because it stands in for that type, names that type in its class name. A class that a dict can be swapped with, and so keeps update, is AttemptsDict. A class whose name says no such type takes method names by the rules above. Attempt.update wrote a file, so it became Attempt.save_fields.

• A test double names what it does. recording_stage_runner records each call that it gets. A name with fake, mock or stub says only that the thing stands in for another, and it hides a use beyond the test, such as a log capture.

A class name is a noun for one kind of thing

PEP 8, chapter 2 of Clean Code, the Swift API Design Guidelines and the .NET Framework Design Guidelines agree on these rules.

• A class name is a noun or a noun phrase, and never a verb. Receipt and AddressParser pass. Cut reads as a verb, Unread as an adjective and Ended as a participle, so each fails.
• A class name carries no empty word. Manager, Processor, Data, Info, Helper and Handler say nothing that the rest of the name does not.
• A variant names its family. An error ends with Error, such as PassDeadlineError. A kind of answer or of event ends with that word where the short name is unclear alone, such as CutAnswer or TerminalEvent.
• A protocol names what a thing is, or what it can do. A protocol for what a thing is reads as a noun, such as Session. A protocol for a capability ends in able, ible or ing, such as Equatable.
• A value class names the value, and not its storage. Receipt passes, and ReceiptData fails. A type that stands in for a standard type follows the rule about method names above.

A test name is a sentence

A test name states the behaviour that the test proves, as one sentence.