<!-- a-sec1-rule1.5.md -->

# Rule 1.5 — You Can Use Words That You Can Include in a Code-Domain Technical Noun Category

> **Source:** Adapted from ASD-STE100 Issue 9
> **Source:** [master.md#sec1-rule1.5](ste-code/grouped/), Rule 1.5

## Original Rule

**Rule 1.5** You can use words that you can include in a technical noun category.

A technical noun is a noun term that refers to a specified concept and is applicable to a subject field.

The dictionary does not include technical nouns because there are too many, and each subject field uses different technical nouns for their texts.

You can find many of these technical nouns in your company glossary or terminology database.

STE gives you a list of categories, with examples, to help you:
- Select technical nouns to put in your company glossary or terminology database.
- Use technical nouns correctly.

You can use technical nouns in procedural and descriptive writing if you can include them in one or more of these twenty-two categories.

[The original specification lists 22 categories. Category titles include: Official parts information; Vehicles or machines, and locations on them; Tools and support equipment, their parts, and locations on them; Materials, consumables, and unwanted material; Facilities, infrastructure, and logistic procedures; Systems, components and circuits, their functions, configurations, and parts; Mathematical, scientific, engineering terms, and formulas; Navigation and geographic terms; Numbers, units of measurement and time (and their symbols); Quoted text; Professional roles, individuals, groups, organizations, and geopolitical entities; Parts of the body; Common personal effects, food, and beverages; Medical terms; Official documents, parts of documentation, standards, and guidelines; Environmental and operational conditions; Colors; Damage terms; Computer science, information and communication technology; Civil and military operations; Law and regulations; Animals, plants, and other life forms.]

## STE-Code Adaptation

**Rule 1.5** You can use words that you can include in a code-domain technical noun category.

A code-domain technical noun is a noun term that refers to a specified concept in software development and is applicable to a subject field.

The controlled terminology does not include all code-domain technical nouns because there are too many, and each project or subject field uses different technical nouns.

You can find many of these code-domain technical nouns in your project glossary or terminology database.

STE-Code gives you a list of categories, with examples, to help you:
- Select code-domain technical nouns to put in your project glossary or terminology database.
- Use code-domain technical nouns correctly.

You can use code-domain technical nouns in procedural and descriptive writing if you can include them in one or more of these nineteen categories.

1. **Code components, modules, and libraries**
   Terms that refer to software parts, packages, and reusable units of code.
   class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility

2. **Computing devices and their components**
   Terms that refer to hardware, devices, and physical computing resources.
   CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal

3. **Development tools, environments, and support equipment**
   Terms that refer to software development tools, IDEs, build systems, and testing frameworks.
   CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack

4. **Data structures, types, and formats**
   Terms that refer to data representation, storage structures, and file formats.
   array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML

5. **Infrastructure, deployment, and platforms**
   Terms that refer to hosting, deployment, containerization, and runtime platforms.
   AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel

6. **Systems, subsystems, and architectural components**
   Terms that refer to system design, architecture patterns, and their parts.
   API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket

7. **Mathematical, algorithmic, and scientific terms**
   Terms that refer to algorithms, computational concepts, and mathematical formulas.
   Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal

8. **Interface elements and navigation**
   Terms that refer to UI components, navigation controls, and layout elements.
   button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip

9. **Numbers, units of measurement, and time**
   Terms that refer to quantitative data, measurements, and time-related information.
   byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB)

10. **Quoted text**
    Terms that refer to texts that you cannot change in code documentation. For example, error messages, code snippets, UI labels, and log output.
    `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused`

11. **Professional roles, teams, and organizations**
    Terms that refer to roles, individuals, organizations, and teams related to software development.
    administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user

12. **Official documents, API references, and standards**
    Terms that refer to documentation types, standards, specifications, and their structural parts.
    API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning

13. **Runtime environments and operational conditions**
    Terms that refer to execution contexts, environment variables, and operating parameters.
    development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine

14. **Colors**
    Terms that refer to colors that identify color-related properties in code (for example, CSS, terminal output, syntax highlighting).
    black, blue, cyan, gray, green, magenta, orange, red, white, yellow
    Colors are adjectives, but STE-Code identifies them as code-domain technical nouns. Comparative and superlative forms of colors (for example, blacker, the reddest) are not permitted in STE-Code.

15. **Defects, errors, and fault terminology**
    Terms that refer to types of software defects, errors, and malfunctions.
    assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error

16. **Computer science, information, and communication technology**
    Terms that refer to concepts, technologies, and architectures in computing and communication.
    AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization

17. **Legal and licensing terms**
    Terms that refer to software licenses, legal documents, and compliance terminology.
    Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty

18. **Database and storage terminology**
    Terms that refer to database concepts, storage systems, and data persistence.
    connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view

19. **Network and protocol terminology**
    Terms that refer to networking concepts, protocols, and communication.
    DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket

The code-domain technical nouns in their related categories are only examples. Rule 1.5 does not give a full list of all possible code-domain technical nouns.

## Code-Domain Explanation

This rule is the primary mechanism for introducing domain-specific vocabulary into STE-Code documentation. The nineteen categories define the boundaries within which you may use technical nouns that are not in the approved STE-Code dictionary. Without this rule, all code-domain terminology would be forbidden, and documentation would become unusable.

### Application by Documentation Type

**README files.** A README introduces a project and describes its purpose, installation, and usage. Use technical nouns from categories 1 (code components), 3 (development tools), 5 (infrastructure), and 17 (legal terms). For example, "This package provides a middleware for Express" uses three code-domain technical nouns — package (category 1), middleware (category 1), and Express (category 5). Each noun names a precise concept that no STE-Code approved word can replace.

**API documentation.** API docs describe endpoints, parameters, return types, and error codes. Use technical nouns from categories 6 (systems), 18 (database), and 19 (network). An API endpoint description such as "The GET /users/:id route returns a JSON object with a user struct" uses route (category 19), JSON (category 4), and struct (category 4). These terms are the subject of the documentation and must appear verbatim.

**Docstrings and inline comments.** Docstrings explain what a function, class, or module does. Use technical nouns from categories 4 (data types), 7 (algorithms), and 15 (defects). A Python docstring such as "Traverse the binary search tree in-order and return a sorted array" uses binary search tree (category 7), in-order (category 7), and array (category 4). The nouns are essential to describe the algorithm correctly.

**Commit messages.** Commit messages record what changed and why. Use technical nouns from categories 1 (code components), 15 (defects), and 18 (database). A commit message such as "Fix race condition in the connection pool that caused a deadlock on PostgreSQL" uses race condition (category 15), connection pool (category 18), deadlock (category 15), and PostgreSQL (category 18). These nouns identify the exact change.

**Error messages.** Error messages report failures to users and developers. Use technical nouns from categories 13 (runtime), 15 (defects), and 19 (network). An error message such as "Connection refused: the TCP socket on port 5432 timed out after 30 seconds" uses TCP (category 19), socket (category 19), port (category 19), and seconds (category 9). These nouns give the user actionable information.

**Test specifications.** Test plans and unit-test descriptions name the component under test and the conditions that apply. Use technical nouns from categories 1 (code components), 4 (data types), and 15 (defects). For example, "The test calls the `parseConfig` function with a null pointer and checks that the function returns an assertion failure" uses function (category 1), null pointer (category 15), and assertion failure (category 15).

### Distinction from Rule 1.1 (Approved Words)

Rule 1.1 requires the use of approved words from the STE-Code dictionary for all common vocabulary. Rule 1.5 is the complement: it permits words outside the dictionary when they name a technical concept. The two rules work together. Use an approved word whenever one exists. Use a code-domain technical noun when no approved word names the concept.

### Distinction from Rule 1.6 (Non-Approved Words Only as Technical Nouns)

Rule 1.6 prohibits all non-approved words except those permitted under Rule 1.5. Rule 1.5 defines what qualifies. Together, Rules 1.5 and 1.6 form a gate: a non-approved word must belong to at least one of the nineteen categories to appear in STE-Code documentation. If the word is neither an approved word (Rule 1.1) nor a code-domain technical noun (Rule 1.5), Rule 1.6 forbids it.

### Requirement: Glossary Registration

ASD-STE100 requires that every technical noun a project uses be registered in the company glossary. STE-Code inherits this requirement. Before you use a code-domain technical noun in documentation, add it to the project glossary or terminology database. The glossary entry must specify:

- The noun term.
- The STE-Code category (or categories) it belongs to.
- The approved meaning in the project context.
- An example sentence that uses the noun correctly.

A project that does not maintain a glossary risks ambiguity: the same noun may mean different things to different readers, which violates Rule 1.11 (one term per concept).

## Paradigm-Specific Guidance

### Object-Oriented Paradigm (Java, C++, C#, Python classes)

In OOP documentation, use technical nouns from categories 1 (code components), 4 (data types), and 6 (systems). Class names, method names, interface names, and design pattern names are code-domain technical nouns. They do not require translation to approved words.

Acceptable: "The `UserRepository` class extends the `BaseRepository` abstract class and implements the `IAuditable` interface."
Explanation: `UserRepository`, `BaseRepository`, and `IAuditable` are code components (category 1). `abstract class` and `interface` are computer science terms (category 16).

```java
// STE-Code compliant docstring for an OOP class
/**
 * The UserRepository class extends the BaseRepository abstract class
 * and implements the IAuditable interface.
 * Use the findById method to get a user struct from the database layer.
 */
public class UserRepository extends BaseRepository implements IAuditable {
    public User findById(Long id) { /* ... */ }
}
```

Acceptable: "The factory method pattern decouples the object creation logic from the client."
Explanation: `factory method pattern` is a design pattern (category 6). `object` is a data structure (category 4). `client` is a system component (category 6).

Not acceptable: "The repo leverages the base to retrieve user data." (Uses non-approved "leverage" — use "use". Uses informal abbreviation "repo" — use full technical noun "repository".)

### Functional Paradigm (Haskell, Elixir, Clojure, Rust)

In functional programming documentation, use technical nouns from categories 7 (algorithms), 4 (data types), and 16 (computer science). Terms such as monad, functor, closure, currying, pattern matching, recursion, and immutability are code-domain technical nouns.

Acceptable: "The function returns an `Option` monad. Use pattern matching to extract the value."
Explanation: `Option` is a data type (category 4). `monad` is a computer science concept (category 16). `pattern matching` is an algorithmic term (category 7).

```haskell
-- STE-Code compliant docstring for a functional pipeline
-- The process function returns an Option monad.
-- Use pattern matching to extract the value from the monad.
process :: [Integer] -> Option Integer
process xs = case safeHead xs of
  Just x  -> Some x   -- Some is a data type (category 4)
  Nothing -> None     -- None is a data type (category 4)
```

Acceptable: "The `fold` function applies a binary operation to each element of the list and accumulates the result."
Explanation: `fold` is an algorithmic term (category 7). `binary operation` is a mathematical term (category 7). `list` is a data structure (category 4).

Not acceptable: "The combinator stuff chains stuff together to make new stuff." (No recognized technical nouns. Replace with specific terms: parser combinator, function, pipeline.)

### Procedural Paradigm (C, Go, Bash)

In procedural code documentation, use technical nouns from categories 4 (data types), 13 (runtime), and 19 (network). Terms such as pointer, struct, mutex, goroutine, channel, file descriptor, and signal are code-domain technical nouns.

Acceptable: "The C function accepts a pointer to a `FILE` struct and returns an integer status code."
Explanation: `pointer` is a data type (category 4). `FILE` is a code component (category 1). `struct` is a data structure (category 4). `integer` is a data type (category 4).

```c
/* STE-Code compliant comment for a procedural function.
 * The read_log function accepts a pointer to a FILE struct
 * and returns an integer status code. */
int read_log(FILE *handle) {
    if (handle == NULL) return -1;  /* null pointer (category 15) */
    /* ... */
    return 0;
}
```

Acceptable: "The Go goroutine reads from the channel. The mutex prevents a race condition."
Explanation: `goroutine` is a runtime term (category 13). `channel` is a data structure (category 4). `mutex` is a computer science term (category 16). `race condition` is a defect term (category 15).

Not acceptable: "The script fires off a subprocess to crunch the numbers." (Uses non-approved "fires off" — use "starts". "crunch" is jargon — use "process".)

### Declarative Paradigm (SQL, Terraform, Kubernetes YAML)

In declarative documentation, use technical nouns from categories 18 (database), 5 (infrastructure), and 12 (official documents). Terms such as SELECT, JOIN, resource, module, provider, pod, deployment, and namespace are code-domain technical nouns. YAML keys and SQL keywords are quoted text (category 10) when referenced verbatim.

Acceptable: "The `SELECT` statement uses an `INNER JOIN` on the `users` and `orders` tables. The query returns a result set."
Explanation: `SELECT` and `INNER JOIN` are quoted text (category 10). `users` and `orders` are database terms (category 18). `result set` is a database term (category 18).

```sql
-- STE-Code compliant comment for a declarative query.
-- The SELECT statement uses an INNER JOIN on the users and orders tables.
-- The query returns a result set with the user name and the order total.
SELECT u.name, o.total
FROM users AS u
INNER JOIN orders AS o ON o.user_id = u.id;
```

Acceptable: "The Terraform `resource` block declares an AWS EC2 instance. The `provider` block configures the AWS region."
Explanation: `resource` and `provider` are infrastructure terms (category 5). `AWS`, `EC2`, and `region` are infrastructure terms (category 5).

Not acceptable: "K8s spins up a bunch of pods inside the thing." (Uses informal "K8s" — use "Kubernetes". Uses non-approved "spins up" — use "starts". Uses imprecise "thing" — use "namespace".)

### Systems Programming (Rust ownership, C memory management)

In systems documentation, use technical nouns from categories 13 (runtime), 4 (data types), and 15 (defects). Terms such as ownership, borrow, lifetime, stack, heap, allocation, deallocation, undefined behavior, and segmentation fault are code-domain technical nouns.

Acceptable: "The Rust compiler enforces the ownership rules. The borrow checker prevents dangling pointers at compile time."
Explanation: `ownership` and `borrow checker` are computer science terms (category 16). `dangling pointers` is a defect term (category 15). `compile time` is a runtime term (category 13).

```rust
// STE-Code compliant comment for a systems function.
// The Rust compiler enforces the ownership rules.
// The borrow checker prevents dangling pointers at compile time.
fn parse_input(buffer: Vec<u8>) -> Result<String, Utf8Error> {
    let text = String::from_utf8(buffer)?;  // heap allocation (category 13)
    Ok(text)
}
```

Acceptable: "The `malloc` function allocates memory on the heap. The caller must call `free` to prevent a memory leak."
Explanation: `malloc` and `free` are code components (category 1). `heap` is a runtime term (category 13). `memory leak` is a defect term (category 15).

Not acceptable: "Rust's thingy stops you from shooting yourself in the foot with memory stuff." (Uses informal "thingy" and "stuff" — replace with "ownership system" and "memory errors". Uses idiom "shooting yourself in the foot" — forbidden by P10.)

## Edge Cases

### Edge Case 1: Framework Names That Are Also Common Words

Some frameworks use common English words as names (for example, React, Vue, Swift, Go, Rust, Elm, Next, Nest). When the framework name also exists as an approved word, context decides the reading. In STE-Code, the framework name is a code-domain technical noun (category 3 or 5) and does not need to follow the approved meaning.

Acceptable: "Use the React framework to build the user interface."
Explanation: `React` is a development tool (category 3). It is not the verb "react" from the dictionary.

Acceptable: "The Go compiler builds the binary."
Explanation: `Go` is a development tool (category 3). It is not the verb "go".

When a sentence is ambiguous without capitalization (for example, "use swift to process the data"), always capitalize framework names or use the full term ("the Swift language", "the Rust compiler") to distinguish them from approved words.

### Edge Case 2: Code Keywords Inside Documentation

Code keywords (`if`, `else`, `for`, `while`, `return`, `class`, `def`, `fn`, `let`, `const`, `var`, `async`, `await`) are quoted text (category 10) when they appear in documentation. They do not need to be technical nouns because they are part of the quoted text category. However, when you use them as English words in a sentence, they must follow approved meanings.

Acceptable: "The `if` statement checks the condition."
Explanation: `if` is quoted text (category 10). The surrounding sentence uses approved words.

Not acceptable: "If the request fails, return a 500." (Missing backticks around `500` — `500` is an HTTP status code, which is quoted text or a number.)

Acceptable: "If the request fails, return `500 Internal Server Error`."
Explanation: The status code is quoted text (category 10).

### Edge Case 3: Abbreviations and Acronyms

Code-domain technical nouns often appear as abbreviations or acronyms (API, JSON, SQL, HTML, CSS, HTTP, TCP, TLS, DNS, URL). These are permissible under Rule 1.5 as technical nouns in categories 16, 18, or 19. However, you must define each abbreviation at its first use in a document, unless the abbreviation is universally understood by the target audience.

Acceptable (first use): "The application programming interface (API) uses Hypertext Transfer Protocol Secure (HTTPS)."
Acceptable (subsequent use): "The API returns a JSON response over HTTPS."

Not acceptable: "The API leverages HTTPS to transmit the payload." (Uses non-approved "leverage" — use "use". Non-approved "transmit" — use "send". Non-approved "payload" — use "data" or define as a technical noun.)

### Edge Case 4: Generated Code and Auto-Generated Documentation

Generated code (for example, OpenAPI specs, protobuf stubs, database migration files) and auto-generated documentation (for example, JSDoc output, Sphinx output) are not required to follow STE-Code rules because a machine, not a human, produces them. However, any human-written comments, descriptions, or annotations inside generated files must follow STE-Code.

Acceptable (generated): `// @ts-expect-error TS1234 — The generated type is incompatible with the runtime type.`
Explanation: The human-written comment follows STE-Code. The generated code itself is exempt.

Not acceptable (human-written comment in generated file): `// this hack works around a funky TS bug`
Explanation: The comment uses non-approved "hack" (use "workaround"), jargon "funky" (use "known defect"), and informal abbreviation "TS" (use "TypeScript").

### Edge Case 5: Project-Specific Internal Names

Projects often name internal components with made-up words, code names, or branded terms (for example, "Project Nightfall", "Hammerhead subsystem", "PhoenixCache"). These are permissible as code-domain technical nouns under category 1 (code components) or category 6 (systems) if they appear in the project glossary. Without glossary registration, such names are non-approved words and violate Rule 1.6.

Acceptable (with glossary): "The PhoenixCache layer stores frequently accessed data in memory."
Explanation: `PhoenixCache` is registered in the project glossary under category 6 (systems).

Not acceptable (without glossary): "The PhoenixCache layer stores frequently accessed data in memory."
Explanation: `PhoenixCache` is not in the glossary. Readers cannot know what it means. Add it to the glossary first.

### Edge Case 6: Numbers as Technical Nouns

Quantitative values that name a configuration, version, status, or port are code-domain technical nouns in category 9 (numbers, units, time) when the value is a fixed, named token rather than a measured quantity. Version numbers (`Node.js 18`), HTTP status codes (`404`), and port numbers (`port 5432`) are quoted text or category 9 nouns and must appear verbatim.

Acceptable: "The service runs on port 5432 and returns `404 Not Found` when the row is absent."
Explanation: `port 5432` is a category 9 noun. `404 Not Found` is quoted text (category 10).

Not acceptable: "The service runs on the default db port and gives a not found error." (Imprecise — use "port 5432" and "`404 Not Found`".)

## Grammar Notes

### Technical Nouns and Articles

In ASD-STE100, technical nouns follow the same article rules as approved nouns. Use "the" for specific instances, "a" or "an" for indefinite instances, and no article for plural general references. This rule applies identically in STE-Code.

Acceptable: "The `UserController` handles a request. The controller returns a response."
Explanation: `UserController` is a specific code component (category 1). `request` and `response` are network terms (category 19).

Acceptable: "Kubernetes pods run in a namespace."
Explanation: `Kubernetes` is a platform (category 5). `pods` is a plural general reference (category 5). `namespace` is an infrastructure term (category 5).

### Technical Nouns as Modifiers

In ASD-STE100, a technical noun can modify another noun to form a compound technical noun phrase. This is common in code documentation. When two technical nouns form a compound, the first noun functions as a modifier and the second as the head noun. Both must belong to a recognized category.

Acceptable: "The Redis cache server stores the session data."
Explanation: `Redis` (category 18) modifies `cache server` (category 6). `session data` is a compound where `session` (category 13) modifies `data` (category 4).

Acceptable: "The PostgreSQL connection pool uses a round-robin scheduler."
Explanation: `PostgreSQL` (category 18) modifies `connection pool` (category 18). `round-robin` (category 7) modifies `scheduler` (category 6).

Not acceptable: "The thing layer processes the stuff queue." (Neither "thing" nor "stuff" is a recognized technical noun.)

### Technical Nouns and the Possessive Form

ASD-STE100 permits the possessive form (`'s`) only for professional roles, organizations, and geopolitical entities (category 11 in STE-Code). Do not use the possessive form with other categories of technical nouns. Use "of" constructions or noun-as-modifier constructions instead.

Acceptable: "The user's session data is encrypted." (Category 11 permits possessive.)
Acceptable: "The configuration of the Docker container is stored in a YAML file." (Category 5, use "of" construction.)
Not acceptable: "The Docker container's configuration is stored in a YAML file." (Category 5 does not permit possessive.)

### Technical Nouns and Pluralization

Technical nouns follow standard English pluralization rules. Acronyms and initialisms form plurals by adding a lowercase "s" without an apostrophe.

Acceptable: "The system uses two APIs and three SQL queries."
Explanation: `APIs` is the plural of `API` (category 19). `queries` is the plural of `query` (category 18).

Not acceptable: "The system uses two API's and three SQL's."
Explanation: The apostrophe in `API's` and `SQL's` incorrectly suggests possession. Use `APIs` and `SQL queries`.

### Technical Nouns and Capitalization

Code-domain technical nouns that are proper nouns (for example, programming language names, company names, product names) keep their original capitalization. Common technical nouns (for example, controller, endpoint, middleware) use lowercase unless they appear as the first word in a sentence.

Acceptable: "The TypeScript compiler checks the types. The controller handles the request."
Explanation: `TypeScript` is a proper noun (category 3). `controller` is a common technical noun (category 1).

Not acceptable: "The typescript compiler checks the Types. The Controller handles the request."
Explanation: `typescript` should be `TypeScript`. `Types` and `Controller` should be lowercase (not first word, not proper nouns).

## Cross-References

- **Rule 1.1 (Approved Words):** Rule 1.1 lists the approved words you must use for all common vocabulary. Rule 1.5 describes the exception: you may use non-approved words if they are code-domain technical nouns. See Rule 1.1 for the complete approved-word dictionary.
- **Rule 1.2 (Part of Speech):** Code-domain technical nouns must be used only as nouns (or noun modifiers). Do not use a technical noun as a verb. See Rule 1.2 for the full restriction on parts of speech.
- **Rule 1.3 (Approved Meanings):** Code-domain technical nouns have the meaning registered in your project glossary. Do not use them with alternative meanings. See Rule 1.3 for the full restriction on approved meanings.
- **Rule 1.4 (Verb and Adjective Forms):** Technical nouns do not have verb forms. If a word that is a technical noun also has a verb form in the dictionary, use the approved verb form for actions and the technical noun form for naming concepts. See Rule 1.4.
- **Rule 1.6 (Non-Approved Words):** Rule 1.6 forbids all non-approved words that are not code-domain technical nouns. Rule 1.5 defines which words qualify. Read Rules 1.5 and 1.6 together.
- **Rule 1.7 (Technical Nouns as Verbs):** A word that is a code-domain technical noun cannot be used as a verb. For example, "host" is a technical noun (category 5); the approved verb is "make available" or "run". See Rule 1.7.
- **Rule 1.8 (Standard Technical Nouns):** Use well-known, widely accepted technical nouns. Do not invent new terms when a standard term exists. See Rule 1.8.
- **Rule 1.9 (Short Technical Nouns):** Prefer short, clear technical nouns over long, obscure ones. See Rule 1.9.
- **Rule 1.11 (One Term per Concept):** Each code-domain technical noun must refer to exactly one concept in your project. Do not use the same noun for two different concepts. See Rule 1.11.
- **Rule 1.12 (Technical Verbs):** Technical verbs (build, deploy, test, lint, compile, debug) are permitted. They are not technical nouns. Do not confuse the two categories. See Rule 1.12.

> **See also:** Rule 1.1 — Approved Words
> **See also:** Rule 1.2 — Part of Speech
> **See also:** Rule 1.3 — Approved Meanings
> **See also:** Rule 1.4 — Verb and Adjective Forms
> **See also:** Rule 1.6 — Non-Approved Words
> **See also:** Rule 1.7 — Technical Nouns as Verbs
> **See also:** Rule 1.8 — Standard Technical Nouns
> **See also:** Rule 1.9 — Short Technical Nouns
> **See also:** Rule 1.11 — One Term per Concept
> **See also:** Rule 1.12 — Technical Verbs

## Summary

Rule 1.5 is the gateway for all domain-specific vocabulary in STE-Code documentation. It permits you to use words outside the approved dictionary when those words name a precise concept in one of the nineteen code-domain categories. The rule requires discipline: register every technical noun in your project glossary, use each noun only with its registered meaning, and do not use technical nouns as verbs. When you follow Rule 1.5 together with Rules 1.1 and 1.6, your documentation uses only two kinds of words: approved STE-Code words for common vocabulary, and code-domain technical nouns for domain-specific concepts. There is no third category.

## Examples

> *Adapted from spec pair:* Non-STE: The mechanic used the thing to get fuel from the tank. | STE: The mechanic used the pump to get fuel from the tank. (engine, tank, pump = technical nouns that name a precise concept; the original ASD-STE100 example shows a non-approved vague word "thing" replaced by the technical noun "pump".)

> *Adapted from spec concept: technical nouns give precision to documentation. Just as STE uses categories like "Vehicles or machines" and "Tools and support equipment" to classify aerospace nouns, STE-Code uses categories like "Professional roles" (frontend developer), "Computer science" (API client, database), and "Interface elements" (UI) to classify code-domain nouns. The non-STE version uses imprecise words ("thing," "storage layer," "screen") that are not clearly identified as technical nouns.*

### Example Group 0: Core Principle

> **Non-STE:** The developer used the thing to get data from the storage layer and put it on the screen.
>
> **STE:** The frontend developer used the API client to get data from the database and show it on the UI.

```ts
// STE-Code compliant: the component shows user data on the UI.
// The frontend developer used the API client to get data from the database
// and show it on the UI.
async function loadUserProfile(userId: string): Promise<void> {
  const apiClient = new ApiClient();          // API client (category 16)
  const user = await apiClient.getUser(userId); // database (category 18)
  renderProfile(user);                         // UI (category 8)
}
```

- **Principle applied:** P1 (use approved words), P11 (one term per concept: name the component, not "thing")
- **Category mapping:** frontend developer (category 11), API client (category 16), database (category 18), UI (category 8)
- **Explanation:** The non-STE version uses "thing" (vague), "storage layer" (not a registered technical noun here), and "screen" (category 2 hardware, not the UI component). The STE version names the exact role, client, store, and interface element.

### Example Group 1: API Documentation

> **Non-STE:** The endpoint leverages the middleware to authenticate the request and then kicks off a background job to crunch the data.
>
> **STE:** The endpoint uses the authentication middleware to check the request. The endpoint then starts a background job to process the data.

```ts
// STE-Code compliant API docstring for a route handler.
// The endpoint uses the authentication middleware to check the request.
// The endpoint then starts a background job to process the data.
app.post('/orders', authMiddleware, async (req: Request, res: Response) => {
  const job = await queue.start(new ProcessOrderJob(req.body)); // background job (category 13)
  res.status(202).json({ jobId: job.id });                     // endpoint (category 19)
});
```

- **Principle applied:** P1 (use approved words: "use" instead of "leverage", "check" instead of "authenticate", "start" instead of "kicks off", "process" instead of "crunch")
- **Category mapping:** authentication middleware (category 16), background job (category 13), endpoint (category 19)
- **Explanation:** The non-STE version uses "leverage" (not approved), "kicks off" (jargon), and "crunch" (jargon). The STE version replaces these with approved verbs and keeps the code-domain technical nouns.

### Example Group 2: README Installation Instructions

> **Non-STE:** First, snag the repo and then cd into it. After that, fire up the dev server.
>
> **STE:** First, clone the repository. Then, change to the repository directory. After that, start the development server.

```md
# Installation

First, clone the repository with Git.

    git clone https://github.com/example/app.git

Then, change to the repository directory.

    cd app

After that, install the dependencies and start the development server.

    npm install
    npm run dev

The development server runs on `http://localhost:3000` (port 3000, category 9).
```

- **Principle applied:** P1 (use approved words: "clone" is a technical verb per Rule 1.12, "change" instead of "cd", "start" instead of "fire up"), P10 (no slang: "snag" is informal)
- **Category mapping:** repository (category 1), development server (category 5)
- **Explanation:** The non-STE version uses slang ("snag"), a shell command as a verb ("cd into"), and jargon ("fire up"). The STE version uses the technical verb "clone" (permitted by Rule 1.12) and approved verbs.

### Example Group 3: Commit Message

> **Non-STE:** Bumped deps and fixed the wonky timeout thing that was breaking prod.
>
> **STE:** Update dependencies. Fix a timeout defect in the connection pool that caused a crash in production.

```text
commit 9f3c1a2
Author: backend developer

Update dependencies. Fix a timeout defect in the connection pool that
caused a crash in production.

- connection pool (category 18): increase the timeout from 5 s to 30 s
- production (category 13): add a retry after the crash (category 15)
```

- **Principle applied:** P1 (use approved words: "update" instead of "bumped"), P10 (no jargon: "wonky" is informal, "prod" is informal), P11 (one term per concept: "defect" instead of "thing")
- **Category mapping:** dependencies (category 1), timeout (category 13), connection pool (category 18), crash (category 15), production (category 13)
- **Explanation:** The non-STE version uses informal language ("bumped", "wonky", "thing", "prod"). The STE version identifies each problem with a precise code-domain technical noun.

### Example Group 4: Error Message

> **Non-STE:** Oops! Something went sideways when the DB tried to do its thing.
>
> **STE:** Error: The PostgreSQL connection pool could not get a connection. The TCP socket timed out after 30 seconds.

```text
Error: The PostgreSQL connection pool could not get a connection.
The TCP socket timed out after 30 seconds.

  at Pool.acquire (postgres/pool.ts:142)
  code: `ETIMEDOUT`            (quoted text, category 10)
  host: `db.internal`          (category 5)
  port: 5432                   (category 9)
```

- **Principle applied:** P1 (use approved words), P10 (no slang: "went sideways", "do its thing"), P11 (one term per concept: name the specific component)
- **Category mapping:** PostgreSQL (category 18), connection pool (category 18), TCP socket (category 19), 30 seconds (category 9)
- **Explanation:** The non-STE version is vague and unprofessional. The STE version names the exact system, the exact component, and the exact timeout value. Users can act on this information.

### Example Group 5: Docstring for a Function

> **Non-STE:** This guy walks the tree and yanks out all the nodes that match the predicate.
>
> **STE:** Traverse the binary search tree. Return a list of nodes that match the predicate function.

```py
def collect_matches(root: TreeNode, predicate: Callable[[TreeNode], bool]) -> list[TreeNode]:
    """Traverse the binary search tree.

    Return a list of nodes that match the predicate function.

    Args:
        root: the root node of the binary search tree (category 7).
        predicate: the predicate function (category 7).

    Returns:
        a list of nodes (category 4) that match the predicate.
    """
    result: list[TreeNode] = []
    _in_order(root, predicate, result)  # in-order traversal (category 7)
    return result
```

- **Principle applied:** P1 (use approved words: "return" instead of "yanks out"), P10 (no slang: "this guy", "walks", "yanks out"), P11 (one term per concept: "traverse" is the standard term for tree navigation)
- **Category mapping:** binary search tree (category 7), nodes (category 4), list (category 4), predicate function (category 7)
- **Explanation:** The non-STE version uses anthropomorphic and informal language. The STE version uses standard algorithmic terminology.

### Example Group 6: Configuration File Comment

> **Non-STE:** Tweak this knob if you want the thing to go faster but be careful not to blow up the memory.
>
> **STE:** Increase this value to reduce the response time. WARNING: Large values can cause a memory leak.

```yaml
# STE-Code compliant config comment.
# Increase this value to reduce the response time.
# WARNING: Large values can cause a memory leak (category 15).
cache:
  max_entries: 10000   # response time (category 7) improves as this value increases
  ttl_seconds: 300     # category 9
```

- **Principle applied:** P1 (use approved words: "increase" instead of "tweak"), P10 (no slang: "knob", "blow up"), P11 (one term per concept: "response time" instead of "go faster")
- **Category mapping:** response time (category 7), memory leak (category 15)
- **Explanation:** The non-STE version uses metaphors ("knob", "blow up") that do not convey technical meaning. The STE version states the effect precisely and adds a warning about the defect.

### Example Group 7: Unit Test Specification

> **Non-STE:** Make sure the parser doesn't choke when we hand it a busted config and check it spits out the right stuff.
>
> **STE:** The test calls the parser with a null pointer. The test checks that the parser returns an assertion failure.

```ts
// STE-Code compliant test documentation.
// The test calls the parser with a null pointer (category 15).
// The test checks that the parser returns an assertion failure (category 15).
test('parser rejects a null pointer config', () => {
  const result = parseConfig(null);
  expect(result.kind).toBe('assertion_failure'); // assertion failure (category 15)
});
```

- **Principle applied:** P1 (use approved words: "call" instead of "hand it", "check" instead of "make sure"), P10 (no slang: "choke", "busted", "spits out", "stuff")
- **Category mapping:** parser (category 1), null pointer (category 15), assertion failure (category 15)
- **Explanation:** The non-STE version uses slang and an imprecise object ("stuff"). The STE version names the component under test and the exact defect term.

### Example Group 8: CI/CD Pipeline Log

> **Non-STE:** The build blew up halfway through because the linter got angry about some sloppy code.
>
> **STE:** The CI/CD pipeline stopped the build. The linter reported a type error in the module.

```text
CI/CD pipeline (category 5) — build stage

  RUN  lint
  ERROR: TypeScript compiler (category 3) found a type error (category 15)
         in the auth module (category 1), file: src/auth/guard.ts:21

  Action: the CI/CD pipeline stopped the build (Rule 1.6 gate).
  Fix: correct the type error, then start the pipeline again.
```

- **Principle applied:** P1 (use approved words: "stop" instead of "blew up", "report" instead of "got angry"), P10 (no slang: "sloppy", "got angry")
- **Category mapping:** CI/CD pipeline (category 5), linter (category 3), type error (category 15), module (category 1)
- **Explanation:** The non-STE version personifies the linter ("got angry") and uses "blew up" for failure. The STE version names the exact stage, tool, and defect, and gives the reader a clear next action.

### Example Group 9: Inline Code Comment

> **Non-STE:** // hack to force the cache to flush itself when the thing gets too big
>
> **STE:** // Workaround: clear the Redis cache when the heap reaches the limit.

```go
// STE-Code compliant inline comment.
// Workaround: clear the Redis cache (category 18) when the heap (category 13)
// reaches the limit. This prevents a memory leak (category 15).
func (c *Cache) maybeEvict() {
    if c.runtime.HeapBytes() > c.maxHeap {
        c.redis.FlushAll() // Redis cache (category 18)
    }
}
```

- **Principle applied:** P1 (use approved words: "clear" instead of "flush itself"), P10 (no slang: "hack", "thing"), P11 (one term per concept: "Redis cache" instead of "the thing")
- **Category mapping:** Redis cache (category 18), heap (category 13), memory leak (category 15)
- **Explanation:** The non-STE comment uses "hack" (non-approved; use "workaround") and "thing" (vague). The STE version names the exact store and runtime component and explains the defect it prevents.

---

<!-- a-sec1-rule1.6.md -->

# Rule 1.6 — Use a Word That Is Not Approved in the Dictionary, Only When It Is a Code-Domain Technical Noun or Part of a Code-Domain Technical Noun

> **Source:** Adapted from ASD-STE100 Issue 9
> **Source:** [master.md#sec1-rule1.6](ste-code/grouped/), Rule 1.6

## Original Rule

**Rule 1.6** Use a word that is not approved in the dictionary, only when it is a technical noun or part of a technical noun.

The dictionary includes some words that you cannot use because they are not approved. But if you can put these words in an applicable category of technical nouns, you can use them as technical nouns in some contexts.

Examples:

The word "base" is not approved in the dictionary and its alternative is "bottom (n)."

> **Non-STE:** Make sure that the two spigots at the base of the unit engage.

("Base" is not permitted when it is related to a surface.)

> **STE:** Make sure that the two spigots at the bottom of the unit engage.

But you can use "base" as a technical noun.

("Base" is a technical noun, category 7, mathematical, scientific, engineering terms, and formulas.)

The same word "base" can go into different categories of technical nouns. This condition occurs when you use the word "base" with different meanings in different contexts.

("Base" is a technical noun, category 5, facilities, infrastructure, and logistic procedures.)

"Backup" is not approved in the dictionary and its alternatives are "emergency (n)" and "auxiliary (adj)." But you can use "backup" as a technical noun.

("Backup" is a technical noun, category 19, computer science, information and communication technology.)

"Backup" is a one-word technical noun. But you can also write "backup file," a two-word technical noun.

("Backup file" is a technical noun, category 19, computer science, information and communication technology.)

"Main" is a word that is not approved, and its alternative is "primary (adj)."

("Main part" is not a technical noun, and it is correct to replace "main" with "primary.")

But you can use "main" as part of a technical noun.

("Main landing gear" is a technical noun. It is incorrect to replace "main" with "primary" here, because "primary landing gear" is not the technical noun that is approved in your company, industry, or subject field.)

If a word is not in the dictionary, you can use it if it is part of a technical noun. In the example that follows, "angular" and "position" are approved but "relative" is not in the dictionary.

(You can use "relative" as part of a technical noun, category 7, mathematical, scientific, engineering terms, and formulas.)

## STE-Code Adaptation

**Rule 1.6** Use a word that is not approved in the controlled terminology, only when it is a code-domain technical noun or part of a code-domain technical noun.

The controlled terminology includes some words that you cannot use because they are not approved. But if you can put these words in an applicable category of code-domain technical nouns, you can use them as code-domain technical nouns in some contexts.

"Handler" is not approved in the controlled terminology and its alternative is "function (n)." A writer must use "function" instead of "handler" when referring to a general processing function.

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.

But you can use "handler" as part of a code-domain technical noun.

> **STE:** The event handler processes each incoming event.
>
> *Adapted from spec pair: "base" can be used as a technical noun in categories 7 and 5. Just as "base" transitions from unapproved word to technical noun when part of a recognized compound term, "handler" transitions from unapproved word to code-domain technical noun when part of "event handler."*

("Event handler" is a code-domain technical noun, category 1, code components, modules, and libraries.)

"Main" is not approved in the controlled terminology and its alternative is "primary (adj)." When "main" is used as a general adjective, it must be replaced with "primary."

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.

But you can use "main" as part of a code-domain technical noun.

> **STE:** Merge the feature branch into the main branch.
>
> *Adapted from spec pair: "Main landing gear" is a technical noun and it is incorrect to replace "main" with "primary." Just as "primary landing gear" is not the approved technical name, "primary branch" is not the approved code-domain technical noun. The official Git term "main branch" must be used.*

("Main branch" is a code-domain technical noun, category 5, infrastructure, deployment, and platforms. It is incorrect to replace "main" with "primary" here, because "primary branch" is not the technical noun that is approved in your project, industry, or subject field.)

"Base" is not approved in the controlled terminology and its alternative is "bottom (n)" for a surface location. When "base" refers to a physical surface, replace it with "bottom."

> **Non-STE:** Make sure that the two connectors at the base of the chassis engage.
>
> **STE:** Make sure that the two connectors at the bottom of the chassis engage.

But "base" is permitted as part of code-domain technical nouns such as "base case" (category 7) and "base class" (category 1).

## Examples

> *Adapted from spec pair:* Non-STE: Make sure that the two spigots at the base of the unit engage.  |  STE: Make sure that the two spigots at the bottom of the unit engage.

### Core Spec Adaptations

The two source examples (handler and main) show the full gate: an unapproved word fails when it is a general noun or adjective, and passes when it is embedded in a recognized code-domain technical noun.

> **Non-STE:** A Python module that uses "handler" as a general noun for any processing unit, and "main" as a general adjective for the primary configuration:

```python
# config_loader.py
def handler(name):
    """The handler loads the config file and returns the data."""
    with open(name) as fh:
        return fh.read()

# start the main worker that uses the handler
if __name__ == "__main__":
    data = handler("app.conf")
    print(data)
```

> **STE:** Replace "handler" with the approved noun "function" when it is a general processing unit. Keep "main" only where it names the entry-point function `main()`; use "primary" for the general adjective. The compound "event handler" may stay because it is a code-domain technical noun (category 1):

```python
# config_loader.py
def load_config(name):
    """The function loads the config file and returns the data."""
    with open(name) as fh:
        return fh.read()

# start the primary worker that uses the function
if __name__ == "__main__":
    data = load_config("app.conf")
    print(data)
```

> **Non-STE:** A Git instruction that treats "main branch" as if it needed replacement, and "base" as a surface word:

```
Check out the primary branch, then copy the files to the base of the build folder.
```

> **STE:** "Main branch" is a recognized Git technical noun (category 5) and stays. "Base" as a surface location becomes "bottom":

```
Check out the main branch, then copy the files to the bottom of the build folder.
```

### README Files

README files mix descriptive prose with tool, library, and package names. The tool names are technical nouns; the prose must use approved words.

> **Non-STE:** A README section that uses unapproved words in the descriptive prose and as verbs:

```markdown
# Acme API

The base setup leverages Express for the main API and MongoDB for the database backend.
The handler backs up the data every night.
```

> **STE:** Replace "base" (general adjective) with "primary", "leverages" with "uses", "handler" with "function", and "backs up" with "makes an auxiliary copy". The package names "Express", "MongoDB", and "database backend" are code-domain technical nouns (categories 3 and 18) and stay:

```markdown
# Acme API

The primary setup uses Express for the main API and MongoDB for the database backend.
The function makes an auxiliary copy of the data each night.
```

> **Non-STE:** A README that refers to a project by a name that contains an unapproved word, then breaks the compound apart:

```
Install react-router. The router in react-router is not approved, so replace it with a controller.
```

> **STE:** "React Router" is a package name — a code-domain technical noun (category 3). Keep the compound whole; do not split the unapproved word out:

```markdown
## Routing
Install `react-router`. The `react-router` package manages client-side routes.
```

### API Documentation

Endpoint paths, HTTP method names, header names, and field names are code-domain technical nouns. The prose that describes them must use approved words.

> **Non-STE:** An OpenAPI description that uses "backup" as a verb and a vague adjective:

```yaml
/post:
  summary: Backups the database and returns a backup ID.
  responses:
    '200':
      description: The backup was made. The handler processed the request.
```

> **STE:** The path `/api/v1/backup` and the field "backup ID" are technical nouns (category 18) and stay. The verb "Backups" becomes "Makes an auxiliary copy"; "handler" becomes "event handler":

```yaml
/api/v1/backup:
  summary: Makes an auxiliary copy of the database. Returns a backup ID.
  responses:
    '200':
      description: The auxiliary copy was made. The event handler processed the request.
```

> **Non-STE:** An endpoint note that uses an unapproved phrasal verb built from a technical noun:

```
POST /api/v1/backup — Authenticates the user and backups the records.
```

> **STE:** "Authenticates" is approved in the controlled terminology for this context; "backups" becomes "makes an auxiliary copy":

```
POST /api/v1/backup — Checks the user and makes an auxiliary copy of the records.
```

### Docstrings and Inline Comments

Docstrings and comments must use approved words; only quoted code names are exempt.

> **Non-STE:** A Python docstring and a comment that use unapproved verbs and a general "base":

```python
def serve(req):
    """Handles the request and returns a response."""
    # base case: handler returns null when req is empty
    if not req:
        return None
    return build(req)
```

> **STE:** "Handles" becomes "processes"; "base case" is a code-domain technical noun (category 7) and stays; "handler" becomes "event handler":

```python
def serve(req):
    """Processes the request and returns a response."""
    # base case: the event handler returns null when req is empty
    if not req:
        return None
    return build(req)
```

> **Non-STE:** A Go comment that uses "handler" as a standalone general word:

```go
// processEdgeCase runs when the base URL is null and the handler times out.
func processEdgeCase() {
    // ...
}
```

> **STE:** "Base URL" is a compound technical noun and stays; "handler" becomes "event handler"; "times out" becomes "runs longer than the timeout":

```go
// processEdgeCase runs when the base URL is null and the event handler runs longer than the timeout.
func processEdgeCase() {
    // ...
}
```

### Commit Messages

Conventional commit prefixes are code-domain technical nouns; the description must follow Rule 1.6.

> **Non-STE:** A commit message that uses "backup" as a verb, "main" as a general adjective, and "handler" alone:

```
feat: add handler for the backup endpoint and the main config loader
```

> **STE:** "Handler" becomes "event handler" (technical noun); "backup" as a standalone adjective becomes "auxiliary"; "main config loader" becomes "primary config loader" because "main" is a general adjective here:

```
feat: add an event handler for the auxiliary-copy endpoint and the primary config loader
```

> **Non-STE:** A commit that treats "backup" and "main" as if they were always unapproved, even inside a named component:

```
fix: run the main backup script before the primary migration
```

> **STE:** "Backup script" is a recognized compound technical noun (category 18) and stays. "Main" as a general adjective becomes "primary":

```
fix: run the backup script before the primary migration
```

> **Non-STE:** A commit where a project glossary defines "main config" as a named file, but the writer still replaces it:

```
chore: update the primary config loader settings
```

> **STE:** Because the project glossary names the file "main config", the compound is a technical noun (category 1) and "main" is permitted:

```
chore: update the main config loader settings
```

### Error Messages

Error messages shown in logs and terminals must use approved words; error codes and type names are technical nouns.

> **Non-STE:** A CI log line that uses two standalone unapproved words:

```
Error: base config file not found. The backup handler will exit.
```

> **STE:** "Base" becomes "primary"; "backup handler" becomes "event handler for auxiliary copies"; "config file" and "event handler" are technical nouns (category 1, 18):

```
Error: primary config file not found. The event handler for auxiliary copies will stop.
```

> **Non-STE:** A runtime error that uses a phrasal verb from a technical noun:

```
Build failed: the main config loader timed out. The backup handler did not start.
```

> **STE:** "Timed out" becomes "ran longer than the timeout" (timeout is a technical noun, category 13, but the phrasal verb is unapproved); "main" becomes "primary"; "backup handler" becomes "auxiliary-copy handler":

```
Build failed: the primary config loader ran longer than the timeout. The auxiliary-copy handler did not start.
```

### Object-Oriented Paradigm (Java, C++, C#, Python Classes)

Class names, interface names, and design-pattern names are code-domain technical nouns (category 1).

> **Non-STE:** A Java class whose docstring uses unapproved verbs and a general "base":

```java
/**
 * The BaseService class handlers requests and backups data.
 * It factories new instances via the MainFactory.
 */
class BaseService { }
```

> **STE:** `BaseService` and `MainFactory` are class names (technical nouns) and stay. "Handlers" becomes "processes"; "backups" becomes "makes auxiliary copies"; "factories" becomes "makes":

```java
/**
 * The BaseService class processes requests and makes auxiliary copies of data.
 * It makes new instances with the MainFactory class.
 */
class BaseService { }
```

> **Non-STE:** A docstring that turns a technical noun into a verb (Rule 1.7 violation):

```python
class Cache:
    """This class singletons the connection for all callers."""
```

> **STE:** "Singleton" is a design-pattern technical noun (category 7); do not use it as a verb. State the pattern with approved words:

```python
class Cache:
    """This class uses the Singleton pattern for the connection used by all callers."""
```

### Functional Paradigm (Haskell, Elixir, Clojure, Rust)

Type names and monad names are technical nouns. "Base case" and "base functor" are permitted compound technical nouns (category 7).

> **Non-STE:** A Haskell comment that uses unapproved verbs and a non-standard "base monad":

```haskell
-- The ReaderT transformer wraps the base monad. It handlers the environment and backups the state.
runApp :: ReaderT Env IO ()
runApp = undefined
```

> **STE:** "Base monad" is permitted only if the library's own docs use it; otherwise use "underlying monad". "Handlers" becomes "supplies"; "backups" becomes "makes an auxiliary copy"; `ReaderT` is a type name (technical noun) and stays:

```haskell
-- The ReaderT transformer wraps the underlying monad. It supplies the environment to each function and makes an auxiliary copy of the state.
runApp :: ReaderT Env IO ()
runApp = undefined
```

> **Non-STE:** A docstring that uses "base case" correctly but verbs wrongly:

```python
def fib(n):
    """Base case returns 1. Recursive case handlers the sum."""
```

> **STE:** "Base case" is a code-domain technical noun (category 7) and stays. "Handlers" becomes "processes":

```python
def fib(n):
    """The base case returns 1. The recursive case processes the sum."""
```

### Procedural Paradigm (C, Go, Bash)

Function names, struct names, and command names are technical nouns. `main()` and the Go `main` package are permitted; "main" as a general adjective is not.

> **Non-STE:** A C comment that uses "handler" and "backup" as standalone general words:

```c
/* The main function calls the backup routine and then the handler for each file. */
void main(void) { }
```

> **STE:** `main` is the entry-point function name (technical noun) and stays. "Backup routine" and "file handler" are code-domain technical nouns (category 1, 18) and stay. Make "handler" explicit as "file handler":

```c
/* The main function calls the backup routine and then the file handler for each file. */
void main(void) { }
```

> **Non-STE:** A Go doc that uses "main" as a general adjective for a goroutine:

```go
// startMain starts the main goroutine that reads from the queue.
func startMain() { }
```

> **STE:** Unless the project convention treats "main goroutine" as a technical noun, "main" becomes "primary":

```go
// startPrimary starts the primary goroutine that reads from the queue.
func startPrimary() { }
```

### Declarative Paradigm (SQL, Terraform, Kubernetes YAML)

Resource names, table names, column names, and property names are technical nouns.

> **Non-STE:** A SQL comment and a Kubernetes manifest comment with unapproved words:

```sql
-- the backup_logs table backups the records each night
SELECT * FROM backup_logs;
```

```yaml
# This ConfigMap holds the base settings. The handler deployment backups the data.
```

> **STE:** `backup_logs` is a table name (technical noun, category 18) and stays; "backups" becomes "keeps auxiliary copies". "ConfigMap" is a resource name (technical noun, category 5) and stays; "base" becomes "primary"; "handler Deployment" stays as a named resource:

```sql
-- the backup_logs table keeps auxiliary copies of the records each night
SELECT * FROM backup_logs;
```

```yaml
# This ConfigMap holds the primary settings. The handler Deployment makes auxiliary copies of the data.
```

### Systems Paradigm (Rust Ownership, C Memory Management)

Dense vocabularies where "unsafe", "raw pointer", and "dangling pointer" are technical nouns.

> **Non-STE:** A Rust comment that uses "unsafe" as a descriptive adjective and "base" as a general word:

```rust
// the main function uses an unsafe block to access the raw pointer.
// the handler drops the base allocation.
fn main() {
    let p = std::ptr::null_mut::<i32>();
    drop(p);
}
```

> **STE:** `main` is the function name (technical noun) and stays. `unsafe` block and `raw pointer` are technical nouns (category 6) and stay. "Handler" becomes "drop handler"; "base allocation" becomes "primary allocation" because "base" is a general adjective there:

```rust
// the main function uses an unsafe block to access the raw pointer.
// the drop handler frees the primary allocation.
fn main() {
    let p = std::ptr::null_mut::<i32>();
    drop(p);
}
```

> **Non-STE:** A comment that uses "unsafe" as a vague descriptive adjective:

```
This approach is unsafe because the buffer is shared.
```

> **STE:** "Unsafe" is not an approved adjective; use the approved adjective with negation. The `unsafe` Rust keyword is a separate technical noun and is backtick-quoted when referring to the construct:

```
This approach is not safe because the buffer is shared.
```

## Decision Procedure — The Technical Noun Gate

Rule 1.6 acts as a gate. An unapproved word may stay in code documentation only when it clears all three tests below. If it fails any test, replace it with the approved alternative from the controlled terminology or restructure the sentence.

### Test 1 — Is the word unapproved?

Approved words never enter this gate. They pass through Rule 1.1 and Rule 1.2 instead. Only unapproved words are tested here.

- "function" is approved — not tested by Rule 1.6.
- "handler" is unapproved — enters the gate.

### Test 2 — Is it a technical noun, or part of a compound technical noun?

The unapproved word must either be a standalone technical noun that fits one of the 19 categories (Rule 1.5), or embedded inside a compound technical noun that fits a category.

- "handler" alone — not a recognized technical noun — fails Test 2.
- "event handler" — recognized design-pattern term, category 1 — passes Test 2.
- "main" alone — not a recognized technical noun — fails Test 2.
- "main branch" — recognized Git term, category 5 — passes Test 2.

### Test 3 — Is it used as a noun in the sentence?

Even a word that passes Test 2 must function as a noun. If it is a verb, adjective, or adverb, it fails Test 3. This is enforced by Rule 1.7.

- "The event handler processes the request." — "event handler" is a noun — passes.
- "This class handlers the request." — "handlers" is a verb — fails Test 3 even though "handler" is a known technical noun. Replace with "processes" or "The request handler processes the request."

### Worked trace

> **Non-STE:** The main config loader backups the data through the handler pipeline.

> **STE:** The primary config loader makes an auxiliary copy of the data through the processing pipeline.

| Word / phrase | Test 1 (unapproved?) | Test 2 (technical noun?) | Test 3 (used as noun?) | Result |
|---|---|---|---|---|
| main config loader | yes | "main" is a general adjective, not part of a recognized compound here | — | replace "main" → "primary" |
| backups | yes | "backup" as a verb is not a technical noun | used as verb | replace with "makes an auxiliary copy" |
| handler pipeline | yes | "handler" + "pipeline" is not a recognized compound | used as noun, but fails Test 2 | replace with "processing pipeline" |

### Compound technical noun checklist

A compound counts as a code-domain technical noun only when all three are true:

1. The words combine to name one concept that the domain recognizes.
2. The compound fits one of the 19 categories.
3. Replacing the unapproved word with its approved alternative changes the recognized name and causes confusion.

If you can swap the unapproved word for its approved alternative and the term still names the same concept, it is NOT a technical noun — make the replacement. If the swap produces a name no one in the domain would recognize, the compound IS a technical noun and the unapproved word is permitted inside it.

### Category overlap — the same word in different categories

The same unapproved word can pass through the gate in different categories when its meaning changes:

- "base" passes as part of "base case" (category 7, algorithmic), "base class" (category 1, code components), and "base URL" (category 8, directory hierarchy). It fails when used as a general adjective for a surface ("the base of the file") where "bottom" applies.
- "cache" passes as a standalone technical noun in category 6 (cache layer), category 16 (cache invalidation), and category 18 (query cache).

In each case the word names a specific concept within a category. It is not a general adjective or verb.

### Distinguishing a technical noun from a descriptive adjective

The hardest judgment in Rule 1.6 is telling a permitted technical noun from a descriptive adjective that must be replaced.

1a. "Check out the main branch before you merge." — "main branch" is a Git convention, a technical noun. Permitted.
1b. "The main configuration has the latest values." — "main" is a descriptive adjective. Replace with "primary".

2a. "The base case returns the single-element array." — "base case" is an algorithmic term. Permitted.
2b. "The base configuration is loaded first." — "base" is a descriptive adjective. Replace with "primary".

3a. "The event handler processes each request." — "event handler" is a design-pattern term. Permitted.
3b. "The handler processes each request." — "handler" alone is not a recognized technical noun. Replace with "function".

Criterion: does the compound appear in the official documentation of the framework, language, or standard? If yes, it is a technical noun. If no, it is descriptive prose and the unapproved words must be replaced.

### Edge Cases

**Edge Case 1 — Framework name that is also an unapproved word.** When a word is the proper name of a tool, it is a technical noun (category 3); when used with its general meaning, it is unapproved.

> **Non-STE:** A setup script that confuses the library name with the general verb:

```bash
# use pandas to data-frame the csv, then express the results as json
python etl.py
```

> **STE:** `pandas` is a library name (technical noun) and stays; "data-frame" as a verb becomes "load ... into a data frame"; "express" as a general verb becomes "use Express" (the framework name, technical noun). Capitalize tool names as published:

```bash
# use pandas to load the csv into a data frame, then use Express to send the results as json
python etl.py
```

**Edge Case 2 — Code keyword that is also an unapproved general word.** Inside backticks a keyword is quoted text (category 10) and exempt; in prose its role decides.

> **Non-STE:** Prose that uses "class" as a general noun and "main" as a general adjective:

```
The class of objects that return a value must not block the main thread.
```

> **STE:** "Class" as a general noun becomes "category"; `return` as a keyword is backtick-quoted (technical noun); "main" as a general adjective becomes "primary":

```
The category of objects that `return` a value must not block the primary thread.
```

**Edge Case 3 — A compound that looks like a technical noun but is not recognized.** A compound qualifies only if a project glossary, framework docs, an industry standard (RFC, W3C), or one of the 19 categories confirms it.

> **Non-STE:** Three invented compounds with unapproved words and no recognized status:

```
The handler pipeline integrates with the backup orchestrator via the main dispatcher.
```

> **STE:** None of the three compounds is recognized, so restructure with approved words: "processing pipeline", "auxiliary-copy service", "primary dispatcher":

```
The processing pipeline integrates with the auxiliary-copy service through the primary dispatcher.
```

**Edge Case 4 — Auto-generated documentation.** Apply Rule 1.6 to the source (docstrings, comments, annotations), not the generated output.

> **Non-STE source:** A C# XML doc that uses unapproved verbs:

```csharp
/// <summary>Handlers the backup operation for the main controller.</summary>
public void Run() { }
```

> **STE source:** Fix at the source; the generated docs inherit compliance:

```csharp
/// <summary>Processes the auxiliary-copy operation for the primary controller.</summary>
public void Run() { }
```

**Edge Case 5 — Open-source project names and brand names.** The project name is always a technical noun (category 3 or 11); descriptive phrases that echo it are still reviewed.

> **Non-STE:** A README that uses a project name as a technical noun but also uses the same word generally:

```
Use Homebrew to install the base packages. Then webpack the main bundle.
```

> **STE:** `Homebrew` is a project name (technical noun) and stays; "base" becomes "primary"; `webpack` as a verb becomes "use `webpack` to make"; "main" becomes "primary":

```
Use Homebrew to install the primary packages. Then use `webpack` to make the primary bundle.
```

## Dictionary and Category Reference

**Controlled-terminology entries referenced by this rule** (see `a-dictionary.md` for the full list):

- **BASE (n) — UNAPPROVED.** Approved alternatives: BOTTOM (n) for a surface or stack position, ROOT (n) for a positional or filesystem root. Permitted as part of compound code-domain technical nouns: "base case" (category 7), "base class" (category 1), "base URL" (category 8).
- **MAIN (adj) — UNAPPROVED.** Approved alternative: PRIMARY (adj). Permitted as part of "main branch" (category 5) and "main function" / `main()` (category 1, the entry-point function).
- **HANDLER (n) — UNAPPROVED.** Approved alternative: FUNCTION (n). Permitted as part of compound technical nouns such as "event handler" and "request handler" (category 1).
- **BACKUP (n, v) — UNAPPROVED.** Approved alternatives: AUXILIARY (adj) for the adjective sense, and the construction "makes an auxiliary copy" for the verb sense. Permitted as part of "backup file", "backup_logs" (category 18), and resource names such as `/api/v1/backup` (category 19).
- **BOTTOM (n), BOTTOM (adj) — APPROVED.** The approved alternative for "base" when it refers to a physical surface or stack position.
- **FUNCTION (n) — APPROVED.** The approved alternative for a standalone unapproved "handler".
- **PRIMARY (adj) — APPROVED.** The approved alternative for "main" used as a general adjective.
- **AUXILIARY (adj) — APPROVED.** One approved alternative for "backup".
- **ROOT (n) — (TN).** Code-domain technical noun for the top-level directory in a filesystem. Permitted (category 5 or 13). Approved alternative for "base" in positional contexts.

**Categories most often used by Rule 1.6** (see `a-categories.md`):

- Category 1 — Code components, modules, and libraries (event handler, base class, main function)
- Category 3 — Development tools, environments, and support equipment (Express, pandas, webpack)
- Category 5 — Infrastructure, deployment, and platforms (main branch, ConfigMap)
- Category 7 — Mathematical, algorithmic, and scientific terms (base case, base functor)
- Category 8 — Codebase navigation and directory hierarchy (base URL, Git root)
- Category 18 — Database and storage terminology (backup_logs, backup file, config file)
- Category 19 — Computer science, information, and communication technology (backup as a resource name, API)

> **See also:** Rule 1.1 — Use Approved Words from the Dictionary, Technical Nouns, or Technical Verbs
> **See also:** Rule 1.2 — Use Approved Words Only as the Specified Part of Speech
> **See also:** Rule 1.5 — You Can Use Words That You Can Include in a Technical Noun Category
> **See also:** Rule 1.7 — Do Not Use Technical Nouns as Verbs
> **See also:** Rule 1.8 — Use Standard, Well-Known Technical Nouns
> **See also:** Rule 1.9 — Prefer Short, Clear Technical Nouns
> **See also:** Rule 1.11 — One Term Per Concept — Be Consistent
> **See also:** Rule 1.12 — Technical Verbs Are Allowed

---

<!-- a-sec1-rule1.7.md -->

# Rule 1.7 — Do Not Use Words That Are Technical Nouns as Verbs

> **Source:** Adapted from ASD-STE100 Issue 9
> **Source:** [master.md#sec1-rule1.7](ste-code/grouped/), Rule 1.7

## Original Rule

**Rule 1.7** Do not use words that are technical nouns as verbs.

Use a technical noun only as a noun or as an adjective that is part of a different technical noun. Do not use the same word as a verb.

Examples:

> *Adapted from spec pair:* Non-STE: Oil the steel surfaces.  |  STE: Apply oil to the steel surfaces.

"Oil" is a technical noun, category 4, materials, consumables, and unwanted material. Do not use "oil" as a verb. Use a different sentence construction that lets you use "oil" as a technical noun.

> **Non-STE:** Oil the steel surfaces.
>
> **STE:** Apply oil to the steel surfaces.

"Snow" is a technical noun, category 16, environmental and operational conditions. Do not use "snow" as a verb. Use a different sentence construction that lets you use "snow" as a technical noun.

> **Non-STE:** Snow the walkway before the shift starts.
>
> **STE:** Remove snow from the walkway before the shift starts.

In some contexts, the same word can be a technical noun and a technical verb. This condition occurs when you can put this word in a technical noun category (rule 1.5) and in a technical verb category (rule 1.12).

> **See also:** Rule 1.5 — You Can Use Words That You Can Include in a Technical Noun Category

> **See also:** Rule 1.12 — You Can Use Verbs That You Can Include in a Technical Verb Category

"Drill" is a technical noun, category 3, tools and support equipment, their parts, and locations on them.

> **STE:** Drill a hole at the intersection of the two lines.

("Drill" is a technical verb, rule 1.12, category 1 a), manufacturing processes, remove material.)

## STE-Code Adaptation

**Rule 1.7** Do not use words that are code-domain technical nouns as verbs.

Use a code-domain technical noun only as a noun or as an adjective that is part of a different code-domain technical noun. Do not use the same word as a verb. Use a different sentence construction that lets you use the word as a code-domain technical noun.

"Database" is a code-domain technical noun, category 18, database and storage terminology. This adapts the spec example where "oil" is a technical noun (category 4, materials). Do not use "database" as a verb. Use a different sentence construction that lets you use "database" as a code-domain technical noun.

> **Non-STE:** Database the user records before the migration.
>
> ```python
> def migrate_users(records):
>     # "database" used as a verb — part of speech violated
>     database(records)
> ```
>
> **STE:** Store the user records in the database before the migration.
>
> ```python
> def migrate_users(records, db):
>     # "store" is the approved verb; "database" stays a noun
>     db.store(records)
> ```

This adapts the spec pair: "Oil the steel surfaces" becomes "Apply oil to the steel surfaces." Just as you cannot use "oil" as a verb in STE, you cannot use "database" as a verb in STE-Code. The STE version uses the approved verb "store" (analogous to "apply") and keeps "database" as a code-domain technical noun.

"Cache" is a code-domain technical noun, category 16, computer science, information and communication technology. This adapts the spec example where "snow" is a technical noun (category 16, environmental and operational conditions). Both "snow" and "cache" are technical nouns in their respective domains that must not be used as verbs.

> **Non-STE:** Cache the API responses to improve performance.
>
> ```javascript
> // Non-STE: "cache" forced into a verb role
> function handleRequest(req, res) {
>   const data = fetchData();
>   cache(data); // unclear: store? read? invalidate?
>   res.send(data);
> }
> ```
>
> **STE:** Store the API responses in the cache to improve performance.
>
> ```javascript
> // STE: "store" is the approved verb; "cache" stays a noun
> function handleRequest(req, res) {
>   const data = fetchData();
>   cache.store(data); // clear action on a clear entity
>   res.send(data);
> }
> ```

NOTE: "Cache" is also a code-domain technical verb (Rule 1.12, category 2 c), system operations. When "cache" is cataloged in your project glossary as both a noun and a verb, you may use it as a verb in its approved verb sense. If your project glossary only lists "cache" as a code-domain technical noun, you must obey Rule 1.7 and use a different sentence construction.

In some contexts, the same word can be a code-domain technical noun and a code-domain technical verb. This condition occurs when you can put this word in a code-domain technical noun category (rule 1.5) and in a code-domain technical verb category (rule 1.12). This adapts the spec example where "drill" can be both a technical noun (a tool) and a technical verb (a manufacturing process).

> **See also:** Rule 1.5 — You Can Use Words That You Can Include in a Technical Noun Category

> **See also:** Rule 1.12 — You Can Use Verbs That You Can Include in a Technical Verb Category

"Log" is a code-domain technical noun, category 18, database and storage terminology. Use "log" only as a noun in this context.

> **STE:** Write a log entry for each failed request.
>
> ```python
> for request in failed_requests:
>     write_log_entry(request.id, request.error)
> ```

"Log" is also a code-domain technical verb, rule 1.12, category 2 c), computer processes and applications, system operations. Use "log" as a verb in this context.

> **STE:** Log each failed request.
>
> ```python
> for request in failed_requests:
>     logger.log(request.id, request.error)
> ```

This distinction is central to Rule 1.7: when a word is a code-domain technical noun in your glossary, do not use it as a verb. When the same word is a code-domain technical verb in your glossary, you may use it as a verb. The key is consistency: decide which part of speech the word has in your project glossary and obey that decision.

## Examples

> *Adapted from spec pair:* Non-STE: Oil the steel surfaces.  |  STE: Apply oil to the steel surfaces.

---

## Code-Domain Explanation

This rule prevents the conversion of code-domain technical nouns into verbs. The rule applies differently to each documentation type because the risk of noun verbing changes with audience and purpose.

### README Files

README files describe a project at a high level. The audience includes new users who may not know that a tool name is not a verb. README files must keep all code-domain technical nouns as nouns. Use an approved verb or a code-domain technical verb to describe the action.

> **Non-STE:** To Docker the application, first Git the repository and then npm the dependencies.
>
> ```markdown
> ## Quick start
> 1. Docker the application with `docker compose up`.
> 2. Git the repository to get the latest code.
> 3. npm the dependencies before you run the tests.
> ```
>
> **STE:** To containerize the application, first clone the repository and then install the dependencies.
>
> ```markdown
> ## Quick start
> 1. Containerize the application with `docker compose up`.
> 2. Clone the repository to get the latest code.
> 3. Install the dependencies with `npm install` before you run the tests.
> ```

> *Principles applied: P7 (do not use technical nouns as verbs), P8 (standard technical nouns). "Docker," "Git," and "npm" are tool names and code-domain technical nouns. Do not use them as verbs. Use "containerize" (a code-domain technical verb, category 1 c), "clone" (a code-domain technical verb, category 2 c), and "install" (a code-domain technical verb, category 2 c).*

### API Reference Documentation

API documentation describes function signatures, parameters, and return values. The function name is a technical code noun. Do not use it as a verb in the description unless the name itself is a verb.

> **Non-STE:** `getUser(id)` — Users the database to retrieve a user.
>
> ```python
> def getUser(id):
>     """Users the database to retrieve a user."""
>     return db.query(id)
> ```
>
> **STE:** `getUser(id)` — Gets a user from the database.
>
> ```python
> def getUser(id):
>     """Gets a user from the database.
>
>     Args:
>         id: The unique identifier of the user.
>     Returns:
>         The user record, or None if not found.
>     """
>     return db.get_user(id)
> ```

> *Principles applied: P7, P1. "Users" is a noun (plural of "user") forced into a verb role. "Retrieve" is not approved. Use the approved verb "get" — which matches the function name `getUser`.*

### Docstrings and Inline Comments

Docstrings must be short and direct. Code-domain technical nouns that appear in comments must stay as nouns. If a comment describes an action, use an approved verb.

> **Non-STE:** # Buffer the output before you socket it to the client.
>
> ```python
> def send_response(output, client):
>     # Buffer the output before you socket it to the client.
>     buffered = buffer(output)
>     socket(client, buffered)
> ```
>
> **STE:** # Write the output to a buffer before you send it through the socket to the client.
>
> ```python
> def send_response(output, client):
>     # Write the output to a buffer before you send it
>     # through the socket to the client.
>     buffered = buffer_writer.write(output)
>     socket_connection.send(client, buffered)
> ```

> *Principles applied: P7, P1. "Buffer" is a code-domain technical noun (category 4, data structures). "Socket" is a code-domain technical noun (category 19, network and protocol terminology). Do not use them as verbs. Use "write" and "send" (approved verbs).*

### Commit Messages

Commit messages use the imperative mood. Code-domain technical nouns must not become verbs in commit messages. If a commit describes an action on a technical noun, use an approved verb to describe the action.

> **Non-STE:** Interface the payment module with the order system.
>
> ```text
> commit subject: Interface the payment module with the order system
> ```
>
> **STE:** Add an interface between the payment module and the order system.
>
> ```text
> commit subject: Add an interface between the payment module and the order system
> ```

> *Principles applied: P7, P13. "Interface" is a code-domain technical noun (category 6, systems and architectural components). Do not use it as a verb. Use the approved verb "add" with the code-domain technical noun "interface." The phrase "between X and Y" follows STE pattern for two entities.*

> **Non-STE:** Middleware the authentication layer.
>
> ```text
> commit subject: Middleware the authentication layer
> ```
>
> **STE:** Add authentication middleware.
>
> ```text
> commit subject: Add authentication middleware
> ```

> *Principles applied: P7, P9. "Middleware" is a code-domain technical noun (category 1, code components). Do not force it into a verb. Use the approved verb "add."*

### Error Messages

Error messages must be clear to all users. End-user error messages must use only approved verbs. Developer-facing error messages may use code-domain technical verbs but must not use code-domain technical nouns as verbs.

> **Non-STE:** (end-user error) Failed to JSON the configuration file.
>
> ```text
> Error: Failed to JSON the configuration file.
> ```
>
> **STE:** (end-user error) Could not parse the configuration file. The JSON format is not correct.
>
> ```text
> Error: Could not parse the configuration file.
> The JSON format is not correct. Check line 42.
> ```

> *Principles applied: P7, P1, P6. "JSON" is a code-domain technical noun (category 4, data structures). Do not use it as a verb. Use "parse" (a code-domain technical verb, category 3 a). For end-user messages, also replace "parse" with a plain-language explanation when possible.*

> **STE:** (developer error) Failed to parse config.json: invalid JSON at line 42.
>
> ```text
> ERROR  config.load: failed to parse config.json:
> invalid JSON at line 42, column 7
> ```

> *Principles applied: P12, P6. "Parse" is a code-domain technical verb for a developer audience. "JSON" stays as a technical code noun, correctly used as an adjective modifying "format" (implied).*

---

## Paradigm-Specific Guidance

### Object-Oriented Programming (Java, C++, C#, Python classes)

Object-oriented documentation has many nouns that developers habitually use as verbs. The most frequent violations of Rule 1.7 in OOP documentation involve class names, design pattern names, and architectural concepts.

| Code-Domain Technical Noun | Incorrect Verb Use | Correct Construction |
|---|---|---|
| interface | "Interface the module with..." | "Add an interface between the module and..." |
| class | "Class the user data model." | "Make a class for the user data model." |
| subclass | "Subclass the base controller." | "Make a subclass of the base controller." |
| singleton | "Singleton the logger." | "Make the logger a singleton." |
| factory | "Factory the parser objects." | "Use a factory to make parser objects." |
| observer | "Observer the state changes." | "Add an observer for the state changes." |
| dependency | "Dependency the service into the controller." | "Inject the service as a dependency into the controller." |

> **Non-STE:** You must abstract the connection pool behind an interface and then factory the pool instances.
>
> ```java
> // Non-STE: "abstract" and "factory" used as verbs
> ConnectionPool pool = abstract(behind(Interface.class));
> List<Pool> instances = factory(pool);
> ```
>
> **STE:** You must make an abstraction of the connection pool behind an interface. Then use a factory to make the pool instances.
>
> ```java
> // STE: nouns stay nouns; approved verbs carry the action
> ConnectionPool pool = makeAbstraction(behind(Interface.class));
> List<Pool> instances = poolFactory.make(pool);
> ```

> *Principles applied: P7, P1. "Abstract" is not approved as a verb in the controlled terminology. "Interface" and "factory" are code-domain technical nouns (category 6 and category 1). Do not use them as verbs. Use "make" (approved verb) with the technical nouns "abstraction" and "factory."*

### Functional Programming (Haskell, Elixir, Clojure, Rust iterators)

Functional programming documentation uses nouns that name mathematical concepts, type classes, and data structures. These nouns must not become verbs.

| Code-Domain Technical Noun | Incorrect Verb Use | Correct Construction |
|---|---|---|
| monad | "Monad the computation." | "Wrap the computation in a monad." |
| functor | "Functor the list." | "Map the function over the functor." |
| combinator | "Combinator the parsers." | "Combine the parsers with a combinator." |
| closure | "Closure the variable." | "Capture the variable in a closure." |
| thunk | "Thunk the expression." | "Wrap the expression in a thunk." |
| lambda | "Lambda the function." | "Write the function as a lambda." |

> **Non-STE:** To monad the optional value, you must functor the inner computation first.
>
> ```haskell
> -- Non-STE: "monad" and "functor" used as verbs
> result = monad optionalValue (functor innerComputation)
> ```
>
> **STE:** To wrap the optional value in a monad, you must map the inner computation over the functor first.
>
> ```haskell
> -- STE: nouns stay nouns; "wrap" and "map" carry the action
> result = wrapInMonad optionalValue (mapOverFunctor innerComputation)
> ```

> *Principles applied: P7, P12. "Monad" and "functor" are code-domain technical nouns (category 7, algorithmic terms). Do not use them as verbs. Use "wrap" (approved verb) with "monad" and "map" (code-domain technical verb, category 3 a) with "functor."*

### Procedural Programming (C, Go, Bash)

Procedural documentation uses nouns that name memory structures, system resources, and data formats. These nouns are frequently misused as verbs in low-level documentation.

| Code-Domain Technical Noun | Incorrect Verb Use | Correct Construction |
|---|---|---|
| buffer | "Buffer the output." | "Write the output to a buffer." |
| pointer | "Pointer the struct." | "Get a pointer to the struct." |
| malloc | "Malloc a block of memory." | "Allocate a block of memory with `malloc`." |
| struct | "Struct the data fields." | "Put the data fields in a struct." |
| heap | "Heap the large objects." | "Allocate the large objects on the heap." |
| stack | "Stack the local variables." | "Put the local variables on the stack." |

> **Non-STE:** Malloc a buffer, then pointer it to the struct you heaped earlier.
>
> ```c
> /* Non-STE: "malloc", "pointer", "heap" used as verbs */
> char *buf = malloc(1024);
> pointer(buf, &req);
> heap(req);
> ```
>
> **STE:** Allocate a buffer with `malloc`. Then set a pointer to the struct that you allocated on the heap.
>
> ```c
> /* STE: "allocate", "set" are approved verbs; nouns stay nouns */
> char *buf = malloc(1024);
> char **ptr = &buf;
> request_t *req = heap_alloc(sizeof(request_t));
> ```

> *Principles applied: P7, P12. "Malloc" is a standard library function and a technical code noun (Rule 1.5). "Buffer," "pointer," and "heap" are code-domain technical nouns (categories 4, 4, and 13). Do not use any of them as verbs. Use "allocate" (code-domain technical verb, category 2 c), "set" (approved verb), and "put" / "allocate" for the remaining constructions.*

### Declarative Programming (SQL, Terraform, Kubernetes YAML)

Declarative documentation uses nouns that name resources, schemas, and configuration objects. The declarative paradigm describes what exists, not what to do, so noun verbing is especially confusing because it implies an imperative action.

| Code-Domain Technical Noun | Incorrect Verb Use | Correct Construction |
|---|---|---|
| table | "Table the user records." | "Store the user records in a table." |
| schema | "Schema the database." | "Apply a schema to the database." |
| index | "Index the column." | "Make an index on the column." |
| YAML | "YAML the configuration." | "Write the configuration in YAML." |
| pod | "Pod the container." | "Put the container in a pod." |
| secret | "Secret the API key." | "Store the API key as a secret." |

> **Non-STE:** First, schema the database. Then table the data and index the primary key column.
>
> ```sql
> -- Non-STE: "schema", "table", "index" used as verbs
> SCHEMA users_db;
> TABLE user_records;
> INDEX id_column;
> ```
>
> **STE:** First, apply a schema to the database. Then store the data in a table and make an index on the primary key column.
>
> ```sql
> -- STE: approved verbs; nouns stay nouns
> CREATE SCHEMA users_db;
> CREATE TABLE user_records (...);
> CREATE INDEX id_idx ON user_records (id_column);
> ```

> *Principles applied: P7, P1. "Schema," "table," and "index" are code-domain technical nouns (category 18, database and storage terminology). Do not use them as verbs. Use "apply," "store," and "make" (approved verbs) with the technical nouns.*

### Systems Programming (Rust ownership, C memory, embedded)

Systems documentation uses nouns that describe memory regions, hardware components, and ownership concepts. These nouns have precise technical meanings that are lost when they are forced into verb roles.

| Code-Domain Technical Noun | Incorrect Verb Use | Correct Construction |
|---|---|---|
| mutex | "Mutex the shared state." | "Lock the mutex before you access the shared state." |
| semaphore | "Smaphore the resource." | "Use a semaphore to control access to the resource." |
| register | "Register the hardware address." | "Write to the register at the hardware address." |
| interrupt | "Interrupt the CPU." | "Send an interrupt to the CPU." |
| DMA | "DMA the buffer to the device." | "Transfer the buffer to the device with DMA." |
| MMU | "MMU the virtual address." | "Map the virtual address through the MMU." |

> **Non-STE:** Mutex the critical section, then DMA the buffer, and finally interrupt the processor.
>
> ```rust
> // Non-STE: "mutex", "DMA", "interrupt" used as verbs
> mutex(critical_section);
> dma(buffer, device);
> interrupt(processor);
> ```
>
> **STE:** Lock the mutex for the critical section. Then transfer the buffer with DMA. Then send an interrupt to the processor.
>
> ```rust
> // STE: approved / code-domain verbs; nouns stay nouns
> mutex.lock();
> dma_transfer(buffer, device);
> send_interrupt(processor);
> ```

> *Principles applied: P7, P12. "Mutex," "DMA," and "interrupt" are code-domain technical nouns (categories 16 and 19). Do not use them as verbs. Use "lock" (code-domain technical verb in systems context, category 2 c), "transfer" (code-domain technical verb, category 3 c), and "send" (approved verb) with the technical nouns.*

---

## Extended Examples

### Example Group A: Tool Name Used as a Verb

> **Non-STE:** You must Docker the application, then Git the changes, and finally Webpack the bundle.
>
> ```bash
> # Non-STE: tool names forced into verb roles
> docker the application
> git the changes
> webpack the bundle
> ```
>
> **STE:** You must containerize the application, then commit the changes, and then bundle the code with Webpack.
>
> ```bash
> # STE: approved verbs; tool names stay nouns
> docker build -t app:1.0 .
> git commit -m "Update application"
> npx webpack --mode production
> ```

> *Principles applied: P7 (do not use technical nouns as verbs), P8 (standard technical nouns), P12 (technical verbs are allowed). "Docker" and "Git" are tool names and code-domain technical nouns. Do not use them as verbs. "Containerize" is a code-domain technical verb (category 1 c). "Commit" is a code-domain technical verb (category 2 b). "Bundle" is a code-domain technical verb (category 1 c). "Webpack" stays as a technical code noun (Rule 1.5) — it names the tool that does the bundling.*

### Example Group B: Data Structure Name Used as a Verb

> **Non-STE:** Queue the jobs, stack the frames, and hash the passwords.
>
> ```python
> # Non-STE: data-structure nouns used as verbs
> queue(jobs)
> stack(frames)
> hash(passwords)
> ```
>
> **STE:** Put the jobs in a queue, push the frames onto the stack, and hash the passwords.
>
> ```python
> # STE: "put" and "push" are approved verbs; "queue" and "stack" stay nouns
> job_queue.put(jobs)
> frame_stack.push(frames)
> hash_passwords(passwords)  # "hash" is a code-domain technical verb
> ```

> *Principles applied: P7, P12. "Queue" and "stack" are code-domain technical nouns (category 4, data structures). "Hash" is a code-domain technical verb (category 3 a) — it is permitted as a verb because it fits a technical verb category. The first two nouns must not be verbed. Use approved verbs "put" and "push" with the technical nouns "queue" and "stack."*

### Example Group C: Brand or Product Name Used as a Verb

> **Non-STE:** You can Google the error message and then Slack the results to your team.
>
> ```text
> Non-STE: "Google the error, then Slack it to the team."
> ```
>
> **STE:** You can search for the error message with Google and then send the results to your team with Slack.
>
> ```text
> STE: "Search for the error with Google, then send the results
> to the team with Slack."
> ```

> *Principles applied: P7, P8, P10. "Google" and "Slack" are brand names and technical code nouns (Rule 1.5). Do not use brand names as verbs. Use "search" (approved verb in the controlled terminology) and "send" (approved verb) with the brand names as nouns.*

> **Non-STE:** Kubernetes the microservices and then Terraform the infrastructure.
>
> ```bash
> # Non-STE: platform names forced into verbs
> kubernetes the microservices
> terraform the infrastructure
> ```
>
> **STE:** Deploy the microservices with Kubernetes and then provision the infrastructure with Terraform.
>
> ```bash
> # STE: approved verbs; platform names stay nouns
> kubectl apply -f microservices.yaml
> terraform apply -var-file=infra.tfvars
> ```

> *Principles applied: P7, P12. "Kubernetes" and "Terraform" are platform names and technical code nouns. Do not use them as verbs. Use "deploy" (code-domain technical verb, category 1 c) and "provision" (code-domain technical verb, category 3 a) with the platform names as nouns.*

### Example Group D: Protocol or Format Name Used as a Verb

> **Non-STE:** JSON the response and then HTTP it to the client.
>
> ```python
> # Non-STE: format and protocol names used as verbs
> body = json(response)
> http(body, client)
> ```
>
> **STE:** Encode the response as JSON and then send it to the client through HTTP.
>
> ```python
> # STE: approved / code-domain verbs; names stay nouns
> body = json_encode(response)
> send_over_http(body, client)
> ```

> *Principles applied: P7, P1. "JSON" and "HTTP" are code-domain technical nouns (category 4, data structures, and category 19, network terminology). Do not use them as verbs. Use "encode" (code-domain technical verb, category 3 a) and "send" (approved verb) with the protocol names as nouns.*

> **Non-STE:** The service must REST the resources and GraphQL the queries.
>
> ```text
> Non-STE: "The service will REST the resources and GraphQL the queries."
> ```
>
> **STE:** The service must expose the resources through a REST API and process the queries through GraphQL.
>
> ```text
> STE: "The service exposes the resources through a REST API and
> processes the queries through GraphQL."
> ```

> *Principles applied: P7, P8. "REST" and "GraphQL" are architectural style names and technical code nouns (category 6 and category 16). Do not use them as verbs. Use "expose" (code-domain technical verb, category 2 b, when describing API surface) and "process" (code-domain technical verb, category 2 c) with the style names as nouns.*

### Example Group E: Architecture Concept Used as a Verb

> **Non-STE:** You must microservice the monolith and then API the new services.
>
> ```text
> Non-STE: "Microservice the monolith, then API the new services."
> ```
>
> **STE:** You must break the monolith into microservices and then add an API for each new service.
>
> ```text
> STE: "Break the monolith into microservices, then add an API
> for each new service."
> ```

> *Principles applied: P7, P1. "Microservice" and "API" are code-domain technical nouns (category 6, systems and architectural components). Do not use them as verbs. Use "break" (approved verb) and "add" (approved verb) with the technical nouns. "Monolith" is also a code-domain technical noun — do not use it as a verb or object of a noun-verb construct.*

> **Non-STE:** We will serverless the compute layer and then container the remaining services.
>
> ```bash
> # Non-STE: architecture nouns forced into verbs
> serverless the compute_layer
> container the services
> ```
>
> **STE:** We will move the compute layer to a serverless architecture and then package the remaining services in containers.
>
> ```bash
> # STE: approved verbs; nouns stay nouns
> deploy compute_layer --target serverless
> docker package services
> ```

> *Principles applied: P7, P9. "Serverless" is an adjective used as a code-domain technical noun (category 6). "Container" is a code-domain technical noun (category 5, infrastructure). Do not force either into a verb role. Use "move" (approved verb) and "package" (code-domain technical verb, category 1 c) with the technical nouns.*

### Example Group F: The Same Word as Noun and Verb — Choose the Correct Form

> **Non-STE:** Log the error and write the log to the log file.
>
> ```python
> # Non-STE: "log" used three ways in one line
> log(error)
> write(log, log_file)
> ```
>
> **STE:** Log the error and write the entry to the log file.
>
> ```python
> # STE: verb "log", noun "entry", noun "log file" kept distinct
> logger.log(error)
> write_log_entry(error, log_file)
> ```

> *Principles applied: P11 (one term per concept), P7. "Log" is both a code-domain technical noun and a code-domain technical verb (Rule 1.12, category 2 c). When you use "log" as a verb, you log data. When you refer to the result, it is a "log entry" or "log file" — not simply "the log" unless the context is clear. Use "entry" to keep the noun and verb distinct.*

> **Non-STE:** The script will script the deployment process.
>
> ```bash
> # Non-STE: "script" (noun) used as a verb
> ./script the deployment
> ```
>
> **STE:** The script will automate the deployment process.
>
> ```bash
> # STE: "automate" is the code-domain technical verb
> ./run_deploy.sh   # automates the deployment process
> ```

> *Principles applied: P7, P1. "Script" is a code-domain technical noun (category 1, code components). Do not use it as a verb. Use "automate" (code-domain technical verb, category 2 c) or an approved verb like "run" with the noun "script": "Run the script to automate the deployment process."*

---

## Edge Cases

### Edge Case 1: Words That Are Both Code-Domain Technical Nouns and Verbs

Some words are cataloged in both a noun category (Rule 1.5) and a verb category (Rule 1.12). These words are the exception to Rule 1.7: you may use them as verbs only in their approved verb sense. The spec example "drill" (noun = tool, verb = manufacturing process) is the exact model.

| Word | Code-Domain Technical Noun (Rule 1.5) | Code-Domain Technical Verb (Rule 1.12) |
|---|---|---|
| cache | Category 16: computer science ("The cache stores responses.") | Category 2 c: system operations ("Cache the responses.") |
| log | Category 18: database and storage ("Write a log entry.") | Category 2 c: system operations ("Log the error.") |
| queue | Category 4: data structures ("Add the job to the queue.") | Category 3 a: algorithmic and data ("Queue the job for processing.") |
| filter | Category 4: data structures or Category 16 ("Apply a filter.") | Category 2 b: UI operations ("Filter the results.") |
| sort | Category 7: algorithmic terms ("Use a merge sort.") | Category 2 b: UI operations ("Sort the list by name.") |
| map | Category 4: data structures ("Use a hash map.") | Category 3 a: algorithmic and data ("Map the function over the list.") |

RULE: Decide which part of speech the word has in your project glossary. If you catalog the word as a noun only, obey Rule 1.7. If you catalog it as both a noun and a verb, use the verb form only when the context matches the verb category description. Do not mix noun and verb uses in the same paragraph without clear context signals.

> **Non-STE:** Filter the results with a filter and then sort the filtered list with a sort.
>
> ```python
> # Non-STE: "filter"/"sort" used as both verb and noun in one sentence
> out = filter(results, with_a=filter)
> out2 = sort(out, with_a=sort)
> ```
>
> **STE:** Filter the results and then sort the list.
>
> ```python
> # STE: verb form implies the noun; no double noun use
> out = filter(results)
> out2 = sort(out, by="name")
> ```

> *Principles applied: P11, P7. When "filter" and "sort" are code-domain technical verbs, do not also use them as nouns in the same sentence. The verb form implies the noun. Use the verb alone for brevity. If you must name the filter or sort mechanism, use a more specific term: "Apply a Bloom filter" or "Use a merge sort algorithm."*

### Edge Case 2: Framework Names That Are Also English Words

Some framework and library names are also common English words with verb senses. For example: "Express" (Node.js framework), "Go" (language), "C" (language), "R" (language), "Boost" (C++ library), "Spring" (Java framework), "React" (JavaScript library — also a verb meaning "to respond"), "Vue" (JavaScript framework — sounds like "view," a verb).

RULE: Framework names are always code-domain technical nouns. Do not use them as verbs, and do not let their English verb meaning interfere with the documentation. Add a qualifier if the context does not make the meaning clear.

> **Non-STE:** Express the middleware and then React to the state changes.
>
> ```javascript
> // Non-STE: framework names used with English verb senses
> express(middleware);
> react(stateChanges);
> ```
>
> **STE:** Write the middleware with Express and then respond to the state changes with React.
>
> ```javascript
> // STE: framework names stay nouns; approved verbs carry meaning
> const app = express();
> app.use(middleware);
> componentDidUpdate() { respondTo(stateChanges); }
> ```

> *Principles applied: P7, P10. "Express" and "React" are framework names and technical code nouns. Do not use their English verb meanings. Use "write" (approved verb) and "respond" (approved verb) with the framework names as nouns.*

> **Non-STE:** Spring the application context and then Go to handle the request.
>
> ```java
> // Non-STE: framework / language names used as verbs
> spring(context);
> go(handleRequest);
> ```
>
> **STE:** Initialize the application context with Spring and then use Go to handle the request.
>
> ```java
> // STE: nouns stay nouns; approved verbs carry the action
> ApplicationContext ctx = Spring.initialize(context);
> router.HandleFunc("/req", goHandler)
> ```

> *Principles applied: P7, P10. "Spring" is a framework name and a technical code noun. "Go" is a language name and a technical code noun. Do not use either as a verb. Use "initialize" (code-domain technical verb, category 2 c) and "use" (approved verb) with the nouns.*

### Edge Case 3: Code Keywords That Look Like Nouns Used as Verbs

Some programming language keywords have the same spelling as nouns but function as keywords. For example: `class` (Java/C++ keyword), `new` (Java/C++ operator), `import` (Python/JavaScript keyword), `return` (ubiquitous keyword), `yield` (Python/C# keyword — also a verb), `async` (JavaScript/Python keyword — not a noun, but sounds like one to non-programmers).

RULE: Keywords are technical code nouns (Rule 1.5) when you refer to them as language features. When they appear in inline code formatting, they are quoted text. Do not use them as verbs in prose.

> **Non-STE:** You must `class` the data model and then `import` the dependencies.
>
> ```python
> # Non-STE: keywords used as verbs in prose and code
> class(data_model)
> import(dependencies)
> ```
>
> **STE:** You must make a `class` for the data model and then add the `import` statements for the dependencies.
>
> ```python
> # STE: keywords quoted as nouns; approved verbs carry action
> class DataModel:
>     pass
> import dependencies
> ```

> *Principles applied: P7, P6. The keywords `class` and `import` are technical code nouns. Do not use them as verbs in prose. Use "make" and "add" (approved verbs) with the keywords as nouns.*

> **Non-STE:** `return` the result and `yield` the intermediate values.
>
> ```python
> # Non-STE: keywords used as verbs
> return(result)
> yield(values)
> ```
>
> **STE:** Use `return` to give back the result and `yield` to supply the intermediate values.
>
> ```python
> # STE: keywords quoted as nouns; approved verbs carry action
> def gen():
>     return result
>     yield from intermediate_values
> ```

> *Principles applied: P7, P6. `return` and `yield` are keywords and technical code nouns. Do not use them as verbs even though they name actions. Use approved verbs "give back" and "supply" (or "send") with the keywords as quoted code nouns. NOTE: "return" is also an approved verb in the controlled terminology. When you mean the general action, use the approved verb "return" — but when you refer to the keyword, format it as inline code: `` `return` ``.*

### Edge Case 4: Generated Code and Auto-Generated Documentation

Generated code and auto-generated documentation do not always obey Rule 1.7. Code generators, protocol buffer compilers, OpenAPI spec generators, and ORM tools produce output that may convert nouns to verbs in symbol names (for example, a generated method named `toJson()` or `asMap()`).

RULE: Rule 1.7 applies to documentation that a human writes. Generated symbol names are exempt, but you must write any surrounding explanation in STE-Code. When you refer to a generated symbol name, treat it as a technical code noun (Rule 1.5). Do not change the generated name even if it violates Rule 1.7.

> **Non-STE:** The generated `UserBuilder` class can `User` the data and `Json` the output.
>
> ```java
> // Non-STE: nouns "User"/"Json" used as verbs in human-written prose
> UserBuilder b = new UserBuilder();
> b.User(data);
> b.Json(output);
> ```
>
> **STE:** The generated `UserBuilder` class makes a `User` object and encodes the output as JSON.
>
> ```java
> // STE: refer to generated symbols as nouns; use approved verbs
> UserBuilder b = new UserBuilder();
> User u = b.build(data);        // generated: makes a User object
> String out = b.toJson(output); // generated: encodes output as JSON
> ```

> *Principles applied: P7, P6. The method names `toJson()` or the class name `UserBuilder` are generated and fixed. Do not use "User" and "Json" as verbs in the prose. Use "makes" (approved verb) and "encodes" (code-domain technical verb, category 3 a) with the technical nouns.*

### Edge Case 5: Multi-Word Technical Nouns Used as Verbs

Some code-domain technical nouns have more than one word. For example, "load balancer" (category 6), "rate limiter" (category 6), "connection pool" (category 18), "feature flag" (category 16), "circuit breaker" (category 6). Developers often drop part of the noun to make a verb: "load balance," "rate limit," "connection pool" (used as a verb), "feature flag" (used as a verb).

RULE: Keep the multi-word technical noun as a noun phrase. Do not drop part of it to make a verb, and do not use the full phrase as a verb. Use an approved verb or a code-domain technical verb to describe the action.

> **Non-STE:** Load balance the requests, then rate limit the clients, and feature flag the new endpoint.
>
> ```python
> # Non-STE: multi-word nouns truncated or used as verbs
> load_balance(requests)
> rate_limit(clients)
> feature_flag(endpoint)
> ```
>
> **STE:** Distribute the requests with a load balancer. Then set a rate limit for the clients. Then put the new endpoint behind a feature flag.
>
> ```python
> # STE: full noun phrases; approved verbs carry the action
> balancer.distribute(requests)
> limiter.set_rate(clients)
> flags.enable(endpoint)
> ```

> *Principles applied: P7, P11. "Load balancer," "rate limit," and "feature flag" are multi-word code-domain technical nouns. Do not drop "balancer" to make "load balance" a verb. Do not use "rate limit" as a verb. Do not use "feature flag" as a verb. Use "distribute" and "set" (approved verbs) and "put" (approved verb) with the full technical noun phrases.*

> **Non-STE:** Circuit break the failing service and connection pool the database connections.
>
> ```python
> # Non-STE: "circuit break" / "connection pool" used as verbs
> circuit_break(service)
> connection_pool(db_connections)
> ```
>
> **STE:** Apply a circuit breaker to the failing service and use a connection pool for the database connections.
>
> ```python
> # STE: full noun phrases; approved verbs carry the action
> breaker.apply(service)
> pool = connection_pool.for_(db_connections)
> ```

> *Principles applied: P7, P1. "Circuit breaker" and "connection pool" are code-domain technical nouns. Do not use them as verbs. Use "apply" (approved verb) and "use" (approved verb) with the full technical noun phrases.*

---

## Cross-References

This rule connects to several other STE-Code rules. Read these rules together to make sure that your documentation obeys all of them.

| Related Rule | Relationship to Rule 1.7 |
|---|---|
| **Rule 1.1** — Use approved words from the dictionary | When a code-domain technical noun cannot be used as a verb, you must replace it with an approved verb from the controlled terminology. Check the dictionary for the correct approved verb. |
| **Rule 1.2** — Use words only as their specified part of speech | This rule is the direct application of Rule 1.2 to technical nouns. If a word is cataloged as a noun in your glossary, Rule 1.2 already forbids using it as a verb. Rule 1.7 extends this principle to all code-domain nouns. |
| **Rule 1.5** — Technical code nouns are allowed | This rule tells you which words are code-domain technical nouns. Rule 1.7 tells you that once a word is in a noun category, you must not use it as a verb. The two rules work together. |
| **Rule 1.12** — Technical verbs are allowed | This is the partner rule to Rule 1.7. Rule 1.12 tells you which words can be code-domain technical verbs. When a word appears in both a noun category (Rule 1.5) and a verb category (Rule 1.12), Rule 1.7 does not apply in the verb context. |
| **Rule 1.8** — Use standard, well-known technical nouns | When you must replace a noun-verb with a different construction, choose a standard technical noun. Do not invent a new noun to replace the verbed noun. |
| **Rule 1.13** — Do not use technical verbs as nouns | This is the inverse rule. Just as Rule 1.7 prevents nouns from becoming verbs, Rule 1.13 prevents verbs from becoming nouns. Together they keep the part-of-speech boundary clear between the two technical word categories. |
| **Rule 1.11** — One term per concept | When you choose an approved verb to replace a noun-verb, use the same approved verb everywhere for the same concept. Do not use "store" in one file and "put" in another for the same action. |
| **Section 3** — Verb rules (tense, mood, voice) | When you replace a noun-verb with an approved verb, the replacement verb must obey all verb rules in Section 3. Use the correct tense, mood, and voice. |

---

## Grammar Notes

### Noun Verbing and the Loss of Precision

When a code-domain technical noun becomes a verb, it lose its precise technical meaning. A "database" is a specific type of storage system with ACID properties, schemas, and query languages. The verb "to database" carries none of that meaning. It is not clear if it means "store," "index," "query," "back up," or "replicate."

The central grammatical justification for Rule 1.7 is that nouns and verbs have different semantic roles. A noun identifies an entity. A verb describes an action, process, or state. When you force a noun into a verb role, you obscure both the entity and the action. The reader must guess which property of the noun you intended to activate as a verb.

> **Non-STE:** The service must database the user data and then cache the results.
>
> ```python
> # Non-STE: "database" and "cache" used as verbs — meaning unclear
> service.database(user_data)
> service.cache(results)
> ```
>
> **STE:** The service must store the user data in the database and then put the results in the cache.
>
> ```python
> # STE: approved verbs name the action; nouns name the entity
> service.store(user_data, in_database=True)
> service.put(results, in_cache=True)
> ```

> *Principles applied: P7, P1. The non-STE version forces "database" and "cache" into verb roles. The reader must guess: does "database" mean store, index, or query? Does "cache" mean store temporarily, retrieve from cache, or invalidate? The STE version removes the guesswork by using approved verbs ("store," "put") that name the specific action, with the technical nouns ("database," "cache") that name the specific entities.*

### The Preposition Phrase Replacement Pattern

The most common repair for a noun-verb is to use an approved verb followed by the technical noun inside a prepositional phrase. This pattern keeps the noun as a noun and adds a precise verb.

| Noun-Verb Construction | STE Repair Pattern | Approved Verb | Preposition |
|---|---|---|---|
| "Cache the data" | "Put the data in the cache" | put | in |
| "Queue the job" | "Add the job to the queue" | add | to |
| "Buffer the output" | "Write the output to a buffer" | write | to |
| "Socket the connection" | "Send the connection through a socket" | send | through |
| "Database the records" | "Store the records in the database" | store | in |
| "Docker the app" | "Package the app in a container" | package | in |
| "Git the changes" | "Commit the changes" (or "Save the changes with Git") | commit / save | (none) / with |
| "JSON the response" | "Encode the response as JSON" | encode | as |

The choice of preposition depends on the relationship between the action and the entity. Use "in" for containment, "to" for destination, "through" for medium, "as" for format or role, and "with" for instrument.

### Noun Verbing in Compound Technical Nouns

When a code-domain technical noun is part of a compound noun phrase (for example, "database migration," "cache invalidation," "buffer overflow"), the noun stays as an adjective modifying another noun. This use is permitted and is not a violation of Rule 1.7. The rule only applies when the noun is the main verb of a clause.

> **STE:** Run the database migration script. (correct — "database" is an adjective modifying "migration script")
> **Non-STE:** Database the migration script. (incorrect — "database" is the main verb)
>
> **STE:** The cache invalidation policy triggers on write. (correct — "cache" is an adjective modifying "invalidation policy")
> **Non-STE:** Cache the invalidation policy. (incorrect — "cache" is the main verb and the meaning is different)

### Affect on Sentence Length

Obeying Rule 1.7 often makes sentences longer. The noun-verb construction is usually shorter (one word) than the approved-verb-plus-prepositional-phrase construction (three to five words). This increase in length is acceptable because the gain in clarity is larger than the loss of brevity.

> **Non-STE:** Cache the response. (3 words)
>
> **STE:** Put the response in the cache. (7 words)

The STE version is four words longer, but it removes all ambiguity. The reader knows exactly which action (put) applies to which entity (cache). The non-STE version is shorter but ambiguous: does "cache" mean store in cache, retrieve from cache, or invalidate the cache?

When sentence length becomes a problem (for example, in docstrings where space is limited), choose the shortest approved verb that gives the correct meaning. "Store the response in the cache" (6 words) is shorter than "Put the response in the cache" and is equally clear.

### The "Log" Exception and the Dual-Category Pattern

The spec gives "drill" as the example of a word that is both a technical noun and a technical verb. In STE-Code, "log" is the most frequent dual-category word. The grammar of "log" as a verb is simple: it takes a direct object (the data to record) and may take a prepositional phrase (the destination).

> **STE:** Log the error to the system log file.
> *"Log" is a code-domain technical verb (category 2 c). "Log file" is a code-domain technical noun (category 18). The sentence uses both correctly.*

The risk is that writers will use "log" as both a noun and a verb in ways that confuse the reader.

> **Non-STE:** Log the log to the log.
>
> ```python
> # Non-STE: "log" used three ways in one line
> log(log, log_file)
> ```
>
> **STE:** Write the log entry to the log file.
>
> ```python
> # STE: verb "log", noun "entry", noun "log file" kept distinct
> logger.log(entry)
> write_log_entry(entry, log_file)
> ```

> *Principles applied: P11, P7. When "log" appears three times with different meanings (verb, noun=entry, noun=file), the sentence is unclear. Use distinct terms: "log entry" for the data, "log file" for the destination, and "log" as the verb.*

### Imperative Mood and Noun Verbing

When a noun-verb appears in an instruction, it forces the noun into the imperative mood — a grammatical form that nouns do not have in English. This creates an ungrammatical construction.

> **Non-STE:** Docker the application. (imperative mood forced onto a noun)
>
> **STE:** Containerize the application. (imperative mood applied to a verb — correct)

The STE version uses "containerize," which is a code-domain technical verb that can correctly take the imperative mood. The non-STE version forces "Docker" into a slot that only verbs can occupy.

---

## Summary Checklist

Use this checklist to check that your documentation obeys Rule 1.7:

1. Find each sentence that has a code-domain technical noun as the main verb.
2. Check your project glossary: is the word cataloged as a noun only, or as both a noun and a verb?
3. If the word is a noun only, use an approved verb with the noun in a prepositional phrase.
4. If the word is both a noun and a verb, make sure you used the verb form correctly.
5. Check that you did not use a tool name, brand name, or protocol name as a verb.
6. Check that you did not drop part of a multi-word technical noun to make a verb.
7. Read the sentence again and make sure the action is clear and the entity is clear.

---

> **See also:** Rule 1.1 — Use Approved Words from the Dictionary
> **See also:** Rule 1.2 — Use Words Only as Their Specified Part of Speech
> **See also:** Rule 1.5 — You Can Use Words That You Can Include in a Technical Noun Category
> **See also:** Rule 1.8 — Use Standard, Well-Known Technical Nouns
> **See also:** Rule 1.11 — One Term per Concept
> **See also:** Rule 1.12 — You Can Use Verbs That You Can Include in a Technical Verb Category
> **See also:** Rule 1.13 — Do Not Use Technical Verbs as Nouns

---

<!-- a-sec1-rule1.8.md -->

# Rule 1.8 — Use Technical Nouns That Are Approved in Your Project, Company, Industry, or Subject Field

> **Source:** Adapted from ASD-STE100 Issue 9
> **Source:** [master.md#sec1-rule1.8](ste-code/grouped/), Rule 1.8

## Original Rule

**Rule 1.8** Use technical nouns that are approved in your company, industry, or subject field.

If your company, industry, or subject field, has an approved technical noun for a system, component, part, or process, use that technical noun. Usually, such technical nouns are included in official parts information and in company documentation.

Example:

> **STE:** The front panel of the phone has a touchscreen and a home button.

("Touchscreen" and "home button" are technical nouns that are approved in your company, industry, or subject field.)

## STE-Code Adaptation

**Rule 1.8** Use code-domain technical nouns that are approved in your project, company, industry, or subject field.

If your project, company, industry, or subject field has an approved code-domain technical noun for a class, module, function, method, variable, component, or process, use that code-domain technical noun. Usually, such code-domain technical nouns are included in your project glossary, API documentation, coding standards, or company documentation.

Do not invent your own names for items that already have established names in your codebase or domain. Consistency with the approved terminology helps all readers understand the documentation and lets them find the exact element in the source tree.

### Examples

> *Adapted from spec pair:* STE: "The front panel of the phone has a touchscreen and a home button." (ASD-STE100 Rule 1.8 gives a compliant example only; there is no Non-STE counterpart in the spec. The code-domain pairs below apply the same principle: use the approved technical noun, not an invented description.)

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel` component.

This adapts the spec example: "The front panel of the phone has a touchscreen and a home button." Just as "touchscreen" and "home button" are technical nouns approved in the industry, `UserTable` and `FilterPanel` are code-domain technical nouns approved in the project. The reader recognizes these exact names from the codebase.

Realistic documentation context (README extract):

```markdown
## Dashboard

The dashboard page renders user data. It uses the `UserTable` component to
show accounts and the `FilterPanel` component to narrow the results by role.
```

> **Non-STE:** The account controller manages login and user profile operations.
>
> **STE:** The `AccountController` manages authentication and user profile operations.

This adapts the spec principle that you must use the approved term. "AccountController" is the code-domain technical noun that is approved in the project (the actual class name in the codebase). The non-STE version uses "account controller," which is not the approved name. Just as you would not replace "touchscreen" with "finger screen" in the spec example, you must not replace `AccountController` with an invented name.

Realistic documentation context (controller docstring and route definition):

```python
# accounts/controllers.py

class AccountController:
    """Manage authentication and user profile operations.

    This is the approved name from the source tree. Do not refer to it as
    "account controller" or "account manager" in the docs.
    """

    def login(self, request: LoginRequest) -> Session:
        ...

    def update_profile(self, user_id: str, data: ProfileData) -> User:
        ...
```

```python
# accounts/routes.py

from accounts.controllers import AccountController

router = APIRouter()
router.add_api_route("/login", AccountController().login, methods=["POST"])
```

---

## Code-Domain Explanation

Rule 1.8 requires that you use the standard, approved technical noun for each concept in your documentation. This rule is not about whether a word is a technical noun (Rule 1.5 covers that). This rule is about which technical noun to choose when more than one name exists for the same concept. The rule applies differently to each documentation type because the degree of available authority changes.

### README Files

README files introduce a project to new users. The project glossary, API docs, and codebase define the approved technical nouns. Use those exact names. Do not substitute descriptive phrases for the approved class names, module names, or component names.

> **Non-STE:** The data display widget shows user information in a table format.
>
> **STE:** The `UserTable` component shows user information.

> *Principles applied: P8 (use standard, well-known technical nouns), P11 (one term per concept). `UserTable` is the approved code-domain technical noun from the codebase. "Data display widget" is an invented description that no reader can map to the code. The STE version uses the exact class name so readers can find it in the source code.*

Realistic README extract:

```markdown
# User Admin

`UserTable` shows user information. It reads from the `UserRepository` and
emits a `rowClick` event when a user selects a row.
```

### API Reference Documentation

API documentation describes endpoints, parameters, return types, and error codes. The API spec and the source code define the approved names. Use the names from the spec — never substitute your own variant even if it seems clearer.

> **Non-STE:** The user retrieval endpoint sends back a user data object.
>
> **STE:** The `GET /users/:id` endpoint returns a `User` object.

> *Principles applied: P8, P11, P5 (technical code nouns are allowed). `GET /users/:id` and `User` are the approved technical nouns from the API spec and the type system. "User retrieval endpoint" and "user data object" are invented phrases that do not match the spec. Readers who search for "user retrieval" will not find the endpoint. Use the exact names.*

Realistic OpenAPI extract:

```yaml
paths:
  /users/{id}:
    get:
      operationId: getUserById
      summary: Return a User object for the given identifier.
      responses:
        '200':
          description: The requested User.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
```

### Docstrings and Inline Comments

Docstrings explain what a function, class, or module does. Use the approved names from the codebase and the project glossary. When a standard industry term exists (for example, "observer pattern"), use it rather than a homegrown description.

> **Non-STE:** This class listens to changes on the data holder and runs callback functions when the data changes.
>
> **STE:** This class implements the observer pattern. It watches a `Subject` and notifies registered `Observer` instances.

> *Principles applied: P8, P11. "Observer pattern," "Subject," and "Observer" are approved technical nouns from the design pattern literature and the codebase. "Listens to changes" and "data holder" are non-standard descriptions. Use the industry-approved name so readers recognize the design pattern immediately.*

Realistic docstring with code:

```python
class EventBus:
    """Implement the observer pattern.

    The EventBus acts as the Subject. Call `subscribe()` to register an
    Observer. When `publish()` runs, the bus notifies every registered
    Observer instance with the event payload.
    """

    def subscribe(self, observer: Observer) -> None:
        self._observers.append(observer)

    def publish(self, event: Event) -> None:
        for observer in self._observers:
            observer.update(event)
```

### Commit Messages

Commit messages record changes to the codebase. Use the approved names for files, classes, functions, and components exactly as they appear in the source tree. A commit message that invents names for code elements is not traceable.

> **Non-STE:** Refactor the auth helper to use the new token validator.
>
> **STE:** Refactor `AuthService` to use `JwtValidator`.

> *Principles applied: P8, P11, P5. `AuthService` and `JwtValidator` are the approved file and class names from the project. "Auth helper" and "token validator" are imprecise descriptions. A developer reading the commit log must be able to map the message to the actual code change. Exact names make that possible.*

Realistic commit and diff header:

```text
commit 4f2c9a1
Author: dev <dev@example.com>
Date:   Mon Aug 01 2026

    Refactor AuthService to use JwtValidator

    Replace the hand-rolled HMAC check in AuthService with the shared
    JwtValidator class. No behavior change.

 src/auth/AuthService.java  | 12 ++++++------
 src/auth/JwtValidator.java |  8 ++++++++
 2 files changed, 14 insertions(+), 6 deletions(-)
```

### Error Messages

Error messages report failures to users and developers. Use the approved component names, not generic descriptions. When a system component fails, the error message must name the component that failed.

> **Non-STE:** Error: The storage system could not process the request.
>
> **STE:** Error: `PostgreSQLConnectionPool` could not execute the query. The pool is exhausted.

> *Principles applied: P8, P11. `PostgreSQLConnectionPool` is the approved component name from the configuration and source code. "Storage system" could mean the database, the cache, the file system, or the object store. The STE version gives the exact component name so the operations team knows which system failed and which configuration to check.*

Realistic application log and user-facing message:

```text
# Application log (developer-facing)
ERROR 2026-08-01T09:14:02Z pool=PostgreSQLConnectionPool
  org.example.db.PoolExhaustedException: could not execute query
  "SELECT * FROM invoices WHERE due < now()"; active=20 max=20

# User-facing message
Error: The PostgreSQLConnectionPool could not execute the query.
The pool is exhausted. Retry the request after a short delay.
```

---

## Paradigm-Specific Guidance

### Object-Oriented Programming (Java, C++, C#, Python classes)

OOP documentation has many names for the same concept: class names, interface names, design pattern names, and architectural terms. Rule 1.8 requires that you use the name from the most authoritative source. For class and interface names, the source code is the authority. For design patterns, the published pattern literature is the authority.

| Concept | Non-Standard Name (avoid) | Approved Technical Noun (use) | Authority |
|---|---|---|---|
| A class that manages user data | user manager, user handler, user service | `UserRepository` | Source code (class name) |
| A method that saves an entity | save method, persist operation, store function | `save()` | Source code (method name) |
| The Factory pattern | maker pattern, creator class, object builder | Factory pattern | Design pattern literature |
| Dependency injection | wiring, hookup, service plumbing | Dependency injection | Industry terminology |
| Model-View-Controller | display pattern, screen architecture | MVC (Model-View-Controller) | Architectural pattern literature |
| An interface for data access | data layer, DB interface, storage contract | `IRepository<T>` | Source code (interface name) |

> **Non-STE:** The user maker class is a singleton. The display part uses a watcher to update the screen when the data part changes.
>
> **STE:** The `UserFactory` class is a Singleton. The `View` uses an `Observer` to update the UI when the `Model` changes.

> *Principles applied: P8, P11. `UserFactory` is the approved class name (source code). "Singleton," "View," "Observer," and "Model" are approved technical nouns from design pattern literature and MVC terminology. "User maker," "display part," "watcher," and "data part" are invented names. The STE version uses the standard terms that every OOP developer recognizes.*

Realistic code and comment:

```java
// UserFactory.java
public class UserFactory {
    private static final UserFactory INSTANCE = new UserFactory();

    public static UserFactory getInstance() {
        return INSTANCE; // Singleton: use the approved pattern name
    }

    public User create(String name) {
        return new User(name);
    }
}

// UserView.java
public class UserView implements Observer {
    private final UserModel model;

    public UserView(UserModel model) {
        this.model = model;
        model.addObserver(this); // Observer updates the UI on change
    }

    @Override
    public void update(Observable o, Object arg) {
        render(model.getState());
    }
}
```

### Functional Programming (Haskell, Elixir, Clojure, Rust iterators)

Functional programming documentation uses mathematical and type-theoretic names. These names are exact and have precise definitions. Do not replace them with informal descriptions even if the description seems clearer.

| Concept | Non-Standard Name (avoid) | Approved Technical Noun (use) | Authority |
|---|---|---|---|
| A type that wraps an optional value | nullable wrapper, maybe container | `Option` / `Maybe` | Language standard library |
| A computation with effects | effectful wrapper, IO box | `IO` monad | Language standard library |
| Function composition | chaining, piping, sequencing | Function composition | Mathematical terminology |
| Pattern matching | destructuring, case analysis, switch on types | Pattern matching | Language specification |
| Immutable data | unchangeable data, frozen data | Immutable data | Functional programming literature |
| Higher-order function | function parameter, callback function | Higher-order function | Mathematical terminology |

> **Non-STE:** The maybe-type holds an optional value. You can chain functions on it without checking for empty values.
>
> **STE:** The `Option` monad holds an optional value. You can compose functions on it without checking for `None`.

> *Principles applied: P8, P11, P5. `Option` and `None` are the approved type and variant names from the language standard library. "Monad" is the approved technical noun from category theory and functional programming. "Maybe-type," "chain functions," and "empty values" are informal descriptions. Use the exact names from the language, the library, and the mathematical foundation.*

Realistic Rust code and doc comment:

```rust
/// Apply `f` to the value inside an `Option`, if present.
///
/// `Option` is the approved name from the standard library; do not call it
/// a "maybe-type". The `None` variant is the approved empty case.
fn map_option<T, U>(input: Option<T>, f: impl FnOnce(T) -> U) -> Option<U> {
    match input {
        Some(value) => Some(f(value)), // pattern matching on the variant
        None => None,
    }
}
```

### Procedural Programming (C, Go, Bash)

Procedural documentation uses names for memory structures, system calls, and standard library functions. These names are defined by the language specification and the POSIX standard. Use the exact names from the authoritative source.

| Concept | Non-Standard Name (avoid) | Approved Technical Noun (use) | Authority |
|---|---|---|---|
| Dynamic memory allocation | heap allocation, memory request, RAM grab | `malloc` | C standard library |
| A data structure grouping | record, compound type, data bundle | `struct` | Language specification |
| A reference to memory | address variable, memory reference, location tracker | `pointer` | Language specification |
| A concurrent execution unit | light thread, green process, concurrent function | `goroutine` (Go) | Language specification |
| Standard output stream | console, terminal, screen output | `stdout` | POSIX standard |
| Environment variables | config vars, system settings, shell vars | Environment variables | POSIX standard |

> **Non-STE:** The C program uses heap allocation to get memory for the data record. It then uses a memory address to pass the record to the processing function.
>
> **STE:** The C program uses `malloc` to allocate memory for the `struct`. It then uses a `pointer` to pass the `struct` to the processing function.

> *Principles applied: P8, P11, P5. `malloc`, `struct`, and `pointer` are approved technical nouns from the C language specification. "Heap allocation," "data record," and "memory address" are descriptions — they are not wrong, but they are not the standard names. Use the standard names that appear in the source code and in the language documentation.*

Realistic C code and comment:

```c
/* Build a record on the heap and pass it by pointer to process(). */
struct record {
    int id;
    char name[64];
};

struct record *make_record(int id, const char *name) {
    struct record *r = malloc(sizeof(struct record)); // malloc, not "heap allocation"
    if (r == NULL) return NULL;
    r->id = id;
    strncpy(r->name, name, sizeof(r->name) - 1);
    return r; // r is a pointer to the struct
}
```

### Declarative Programming (SQL, Terraform, Kubernetes YAML)

Declarative documentation uses resource type names, keyword names, and configuration block names. These names are defined by the spec, the provider documentation, or the API reference. Use the exact names — do not paraphrase them.

| Concept | Non-Standard Name (avoid) | Approved Technical Noun (use) | Authority |
|---|---|---|---|
| A Terraform virtual machine resource | VM block, compute instance, server resource | `aws_instance` | Terraform provider docs |
| A Kubernetes pod spec | container group, deployment unit, pod config | `Pod` / `PodSpec` | Kubernetes API reference |
| An SQL SELECT query | data fetch, retrieval query, read statement | `SELECT` statement | SQL standard |
| A database transaction | atomic block, all-or-nothing unit, DB transaction | `TRANSACTION` | SQL standard |
| A Terraform output value | export block, return value, output config | `output` | Terraform language docs |
| A Kubernetes namespace | isolation zone, project space, resource group | `Namespace` | Kubernetes API reference |

> **Non-STE:** The Terraform config declares a compute instance in the AWS cloud. It then exports the IP number.
>
> **STE:** The Terraform configuration declares an `aws_instance` resource. It then exports the `public_ip` with an `output` block.

> *Principles applied: P8, P11, P5. `aws_instance`, `public_ip`, and `output` are approved technical nouns from the Terraform provider documentation and the HCL language specification. "Compute instance," "AWS cloud," "IP number," and "exports" are descriptions that do not match the actual resource type names or attribute names. Users who copy "compute instance" into a Terraform file will get a syntax error. Use the exact resource type name.*

Realistic Terraform extract:

```hcl
resource "aws_instance" "web" {
  ami           = "ami-0abc1234"
  instance_type = "t3.micro"
}

output "public_ip" {
  description = "The public IP address of the web server."
  value       = aws_instance.web.public_ip
}
```

### Systems Programming (Rust ownership, C memory, embedded)

Systems documentation uses names for memory regions, hardware components, and ownership concepts. These names have precise meanings defined by the language specification, the hardware reference manual, or the operating system standard.

| Concept | Non-Standard Name (avoid) | Approved Technical Noun (use) | Authority |
|---|---|---|---|
| Rust ownership transfer | move operation, ownership handoff, transfer | `move` semantics | Rust language reference |
| Rust borrowing | reference pass, temporary access, pointer loan | `borrow` | Rust language reference |
| A memory region for dynamic allocation | dynamic memory, free store, malloc area | `heap` | Operating system / language spec |
| A memory region for automatic allocation | automatic memory, call stack, function memory | `stack` | Operating system / language spec |
| A mutual exclusion lock | thread lock, access guard, concurrency lock | `Mutex` | Language standard library |
| An interrupt service routine | interrupt function, handler code, ISR function | `ISR` (Interrupt Service Routine) | Hardware reference manual |

> **Non-STE:** Rust moves ownership when you give a value to another variable. You can also lend a reference without giving ownership.
>
> **STE:** Rust applies `move` semantics when you assign a value to another binding. You can also `borrow` a reference without transferring ownership.

> *Principles applied: P8, P11, P5. `move` and `borrow` are the approved technical nouns from the Rust language reference. "Give a value" and "lend a reference" are English paraphrases that do not match the language specification. Readers who learn Rust from the official documentation expect the terms "move" and "borrow." Use these terms so your documentation matches the language reference.*

Realistic Rust code and comment:

```rust
fn process(data: Vec<u8>) {
    let owned = data;        // `move` semantics: ownership transfers to `owned`
    let len = owned.len();   // `borrow` a shared reference to read `owned`
    println!("bytes: {len}");
} // `owned` drops here; no transfer back needed
```

---

## Extended Examples

### Example Group A: Class Name vs. Descriptive Phrase

> **Non-STE:** The payment processing handler checks the card information and talks to the bank system to complete the transaction.
>
> **STE:** The `PaymentProcessor` validates the `CardDetails` and sends a request to the `BankGateway` to complete the `Transaction`.

> *Principles applied: P8 (use standard, well-known technical nouns), P11 (one term per concept), P5 (technical code nouns). `PaymentProcessor`, `CardDetails`, `BankGateway`, and `Transaction` are the approved class names from the source code. "Payment processing handler," "card information," "bank system," and "the transaction" are descriptions. The STE version uses the exact class names so every reader can find these classes in the codebase.*

Realistic module documentation:

```python
# payments/service.py
class PaymentProcessor:
    """Validate a CardDetails object and complete a Transaction."""

    def __init__(self, gateway: BankGateway) -> None:
        self.gateway = gateway

    def charge(self, card: CardDetails, amount: Money) -> Transaction:
        card.validate()
        return self.gateway.submit(card, amount)
```

### Example Group B: Pattern Name vs. Homemade Description

> **Non-STE:** The class uses a setup where one object notifies many waiting objects when its state changes.
>
> **STE:** The class implements the Observer pattern. The `Subject` notifies all registered `Observer` instances when its state changes.

> *Principles applied: P8, P11, P9 (prefer short, clear technical nouns). "Observer pattern" is the industry-approved name from the Gang of Four design patterns. "Subject" and "Observer" are the approved role names from the pattern. "A setup where one object notifies many waiting objects" is a long description that no reader will recognize as the Observer pattern. The STE version uses the standard name so readers immediately understand the design.*

Realistic interface definitions:

```typescript
interface Subject {
  attach(observer: Observer): void;
  detach(observer: Observer): void;
  notify(): void;
}

interface Observer {
  update(subject: Subject): void;
}
```

### Example Group C: Protocol Name vs. Generic Description

> **Non-STE:** The service uses secure web communication to send data between the client and the server.
>
> **STE:** The service uses HTTPS to send data between the client and the server.

> *Principles applied: P8, P9. "HTTPS" is the approved technical noun from the IETF standards. "Secure web communication" is a description that could refer to HTTPS, TLS, SSH, or a VPN. The STE version uses the exact protocol name so readers know which standard applies and can refer to the RFC.*

Realistic configuration snippet:

```yaml
server:
  # Use HTTPS (RFC 9110), not a vague "secure web communication" setting.
  protocol: https
  tls:
    certificate: /etc/ssl/certs/server.pem
    key: /etc/ssl/private/server.key
```

### Example Group D: Framework Feature Name vs. Informal Description

> **Non-STE:** React's function that manages state and side effects runs after the component draws on the screen.
>
> **STE:** React's `useEffect` hook runs after the component renders.

> *Principles applied: P8, P11, P5. `useEffect` is the approved API name from the React documentation. "Hook" is the approved category name for this type of function. "Render" is the approved term for the drawing phase. "Function that manages state and side effects" and "draws on the screen" are informal descriptions. Use the exact API names and React terminology.*

Realistic component code:

```jsx
import { useEffect, useState } from "react";

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);

  // useEffect runs after the component renders (the approved term).
  useEffect(() => {
    fetch(`/users/${userId}`).then((r) => r.json()).then(setUser);
  }, [userId]);

  return <div>{user ? user.name : "Loading…"}</div>;
}
```

### Example Group E: Algorithm Name vs. Plain-Language Description

> **Non-STE:** The search function splits the sorted list in half again and again until it finds the target value or runs out of items.
>
> **STE:** The `binarySearch` function applies the binary search algorithm to the sorted array. It returns the index of the target value or `-1` if the value is not present.

> *Principles applied: P8, P11, P9. "Binary search algorithm" is the approved technical noun from computer science literature. "Splits the sorted list in half again and again" is a description of how binary search works, but it does not name the algorithm. A reader who knows binary search will recognize the name immediately. A reader who does not can look up "binary search" in any algorithms textbook. A description cannot be searched for as easily as a standard name.*

Realistic implementation and docstring:

```python
def binary_search(items: list[int], target: int) -> int:
    """Apply the binary search algorithm to a sorted array.

    Return the index of `target`, or -1 if `target` is not present.
    """
    low, high = 0, len(items) - 1
    while low <= high:
        mid = (low + high) // 2
        if items[mid] == target:
            return mid
        if items[mid] < target:
            low = mid + 1
        else:
            high = mid - 1
    return -1
```

### Example Group F: Configuration Key vs. Generic Description

> **Non-STE:** Set the database location setting to point to your local database server address.
>
> **STE:** Set the `DATABASE_URL` environment variable to your local PostgreSQL connection string.

> *Principles applied: P8, P11, P5. `DATABASE_URL` is the approved configuration key name from the project's `.env.example` file. "Database location setting" is a description that does not tell the user which key to set. The STE version uses the exact key name so the user can copy it directly into their configuration file. "PostgreSQL" is the approved database name (not "database server"). "Connection string" is the approved technical noun for the value format.*

Realistic configuration files:

```bash
# .env.example  — use the approved key name, not "database location setting"
DATABASE_URL=postgresql://user:password@localhost:5432/app
```

```python
# settings.py
import os

# Read the approved key name from the environment.
DATABASE_URL = os.environ["DATABASE_URL"]  # PostgreSQL connection string
```

---

## Edge Cases

### Edge Case 1: When the Codebase Uses a Non-Standard Name for a Standard Concept

Sometimes a codebase names a class, module, or function with a term that is not the industry standard. For example, a codebase might call a repository class `DataStore` instead of `Repository`, or a factory class `Maker` instead of `Factory`. Which name does Rule 1.8 require?

RULE: The codebase name is the primary authority for code elements. If the class is named `DataStore`, use `DataStore` in documentation that refers to that specific class. However, you may also mention the industry-standard name to help readers understand the concept.

> **STE:** The `DataStore` class (a Repository pattern implementation) manages all database access.

> *Principles applied: P8, P11. `DataStore` is the approved name from the source code. "Repository pattern" is the industry-approved name. Use both: the codebase name for traceability and the industry name for comprehension. Do not replace the codebase name with the industry name — that breaks the link between the documentation and the code.*

Realistic docstring:

```python
class DataStore:
    """Repository pattern implementation for all database access.

    The class name in the source tree is `DataStore`. Use that exact name in
    docs. "Repository" is the industry pattern name, shown here for context.
    """
```

### Edge Case 2: When Two Industry Standards Compete for the Same Concept

Some concepts have two accepted names from different communities. For example, "callback" vs. "handler" vs. "listener" (all refer to a function that responds to an event). "Hash map" vs. "dictionary" vs. "associative array" (all refer to a key-value data structure). "Argument" vs. "parameter" (both refer to inputs to a function, with a narrow technical distinction that most documentation ignores).

RULE: Choose one name and use it consistently (Rule 1.11). Register your choice in the project glossary. Prefer the name that matches your language ecosystem: Java projects use "map," Python projects use "dictionary," JavaScript projects use "object" or "Map."

> **Non-STE:** The callback handler receives the event and passes it to the listener function.
>
> **STE:** The `EventHandler` callback receives the event and passes it to the registered listener.

> *Principles applied: P11, P8. The non-STE version uses "callback," "handler," and "listener" interchangeably. The STE version assigns each term a distinct meaning: `EventHandler` is a class, "callback" is the function type, and "listener" is the registered consumer. Register these distinctions in the project glossary.*

Realistic event code:

```typescript
type Callback = (event: Event) => void;

class EventHandler {
  private listeners: Callback[] = [];

  on(listener: Callback): void {
    this.listeners.push(listener); // "listener" = registered consumer
  }

  emit(event: Event): void {
    for (const listener of this.listeners) listener(event);
  }
}
```

### Edge Case 3: When the Approved Name Is an Acronym or Initialism

Many standard technical nouns are acronyms or initialisms: API, JSON, SQL, HTML, CSS, HTTP, JWT, ORM, MVC. Rule 1.8 requires that you use the approved acronym. However, you must also define the acronym at its first use in each document unless the audience is known to understand it.

> **STE:** The application programming interface (API) returns JavaScript Object Notation (JSON). The JSON Web Token (JWT) in the response header identifies the user.

> *Principles applied: P8, P11. Define each acronym at first use. After the definition, use only the acronym. Do not alternate between the full form and the acronym — that suggests two different concepts (violates P11).*

> **Non-STE:** The application programming interface returns JSON. The API also sends a JWT (JSON Web Token).
>
> **STE:** The API returns JSON. The API also sends a JWT.

> *Principles applied: P11. After the first definition, use only the acronym. "Application programming interface" and "API" refer to the same concept — using both suggests a distinction that does not exist.*

Realistic API documentation extract:

```markdown
## Authentication

The application programming interface (API) returns JavaScript Object
Notation (JSON). The JSON Web Token (JWT) in the response header identifies
the user. After this definition, the document uses only "API", "JSON", and
"JWT" so the reader is not misled into thinking they are different concepts.
```

### Edge Case 4: When a Framework Renames a Standard Concept

Frameworks sometimes rename standard concepts with project-specific vocabulary. React calls its UI building blocks "components." Vue calls them "components." Angular calls them "components." All three use the same term — no conflict. But Django calls them "views" and "templates." Ruby on Rails calls them "views" and "partials." Phoenix calls them "views" and "templates."

RULE: In documentation for a specific framework, use the framework's approved name. In general documentation (not framework-specific), use the most widely recognized name and mention the framework variant if necessary.

> **Non-STE:** (Django documentation) The component renders the HTML and the controller handles the request.
>
> **STE:** (Django documentation) The view renders the HTML and the view handles the request.

> *Principles applied: P8, P11. Django uses "view" for both the rendering function and the request handler. Using "component" and "controller" (terms from other frameworks) in Django documentation confuses Django developers. Use the framework's own terminology.*

> **STE:** (General documentation) The framework's controller (called a "view" in Django and a "handler" in Phoenix) processes the request.

> *Principles applied: P8, P11. General documentation uses the most common term ("controller") and acknowledges the framework-specific variants in parentheses. This helps readers from different ecosystems understand the concept.*

Realistic Django view:

```python
# polls/views.py  — Django uses "view", not "component" or "controller"
from django.http import HttpResponse
from django.shortcuts import render

def index(request):
    latest = Question.objects.order_by("-pub_date")[:5]
    return render(request, "polls/index.html", {"latest": latest})
```

### Edge Case 5: When the Approved Name Changes During a Migration or Refactor

During migrations and refactors, the codebase may have two names for the same concept: the old name (still in some files) and the new name (in the refactored files). Documentation must choose which name to use.

RULE: Use the target name (the name after the migration is complete). If you must mention the old name (for example, in a migration guide), use it only in quoted text (Rule 1.5, category 10) and always with a note that it is deprecated.

> **STE:** The `UserService` class (formerly `UserManager`) handles user authentication. DEPRECATED: `UserManager` is the old name. Use `UserService` in new code.

> *Principles applied: P8, P11. `UserService` is the approved target name. `UserManager` is the deprecated name, shown only for migration context. After the migration is complete, remove all references to `UserManager` from the documentation.*

Realistic migration guide extract:

```markdown
## Renaming UserManager to UserService

The `UserService` class (formerly `UserManager`) handles user authentication.

> DEPRECATED: `UserManager` is the old name. Use `UserService` in new code.
> The old symbol is removed in version 3.0.
```

### Edge Case 6: Package Managers and Ecosystem-Specific Name Variants

The same package may have different names in different package registries. For example, `lodash` (npm) vs. `lodash` (RubyGems — a different library), `python-dotenv` (PyPI) vs. `dotenv` (npm), `org.apache.commons:commons-lang3` (Maven) vs. `apache-commons-lang` (system package).

RULE: In documentation for a specific ecosystem, use the name from that ecosystem's registry. Include the registry-qualified name (for example, `pip install python-dotenv`) in installation instructions. In general documentation, use the most common name and note ecosystem variants.

> **Non-STE:** Install the dotenv package to load environment variables.
>
> **STE:** Install the `python-dotenv` package with `pip` to load environment variables.

> *Principles applied: P8, P11. "Dotenv package" is ambiguous — it could be the npm package, the PyPI package, or the Ruby gem. The STE version gives the exact PyPI package name (`python-dotenv`) and the exact tool (`pip`). This instruction can be copied directly into a terminal.*

Realistic installation section:

```markdown
## Install

Install the `python-dotenv` package with `pip` to load environment variables:

    python -m pip install python-dotenv

(For Node.js projects, the equivalent is `npm install dotenv`.)
```

---

## Cross-References

This rule connects to several other STE-Code rules. Read these rules together to make sure that your documentation obeys all of them.

| Related Rule | Relationship to Rule 1.8 |
|---|---|
| **Rule 1.1** — Use approved words from the dictionary | Rule 1.1 controls common vocabulary. Rule 1.8 controls which technical noun to choose among competing candidates. When a common word and a technical noun both name the same concept, use the technical noun from the approved source. |
| **Rule 1.2** — Use words only as their specified part of speech | The approved technical noun is a noun. Do not use it as a verb or an adjective that lacks a head noun. See also Rule 1.7 for the full restriction on noun verbing. |
| **Rule 1.3** — Use words only with their approved meanings | The approved technical noun has the meaning registered in your project glossary or the industry standard. Do not assign it a different meaning even if the word seems clearer with that meaning. |
| **Rule 1.5** — Technical code nouns are allowed | Rule 1.5 defines which words can be code-domain technical nouns. Rule 1.8 tells you to choose the standard, well-known code-domain technical noun when more than one candidate exists. |
| **Rule 1.6** — Non-approved words only when they are technical code nouns | When a concept has both an approved code-domain technical noun and a common English description, Rule 1.8 requires the technical noun. Rule 1.6 reinforces this by forbidding the common description if it is not an approved word. |
| **Rule 1.7** — Do not use technical nouns as verbs | The approved technical noun that you choose under Rule 1.8 must stay as a noun. Rule 1.7 forbids using it as a verb regardless of which name you chose. |
| **Rule 1.9** — Prefer short, clear technical nouns | When two approved technical nouns both name the same concept, Rule 1.9 breaks the tie: choose the shorter one. Rule 1.8 provides the set of approved candidates. Rule 1.9 ranks them. |
| **Rule 1.10** — No slang, jargon, or regional terms | Slang and jargon are often invented names for standard concepts. Rule 1.10 forbids them. Rule 1.8 tells you to replace them with the standard, approved technical noun. The two rules work together: Rule 1.10 removes the non-standard name; Rule 1.8 supplies the standard replacement. |
| **Rule 1.11** — One term per concept | Rule 1.11 requires consistency: one concept, one name. Rule 1.8 provides the decision process for choosing that one name. When you choose an approved technical noun under Rule 1.8, Rule 1.11 guarantees that you use it everywhere. |
| **Rule 1.12** — Technical verbs are allowed | Some concepts have both a technical noun and a technical verb form (for example, "cache" is both a noun and a verb). Rule 1.8 applies to the noun form. Rule 1.12 applies to the verb form. When you use the verb form, choose the approved technical verb — but when you name the concept in documentation, use the approved technical noun. |
| **Rule 1.14** — Use American English spelling | When the industry-standard technical noun has different spellings in different English variants (for example, "color" vs. "colour" in CSS property names), use the spelling from the specification. CSS uses "color" (American English). HTML uses "colour" in some deprecated attributes. Follow the specification, not Rule 1.14, for spec-defined names. For all other technical nouns, use American English spelling. |

> **See also:** Rule 1.1 — Use approved words from the dictionary
> **See also:** Rule 1.2 — Use words only as their specified part of speech
> **See also:** Rule 1.3 — Use words only with their approved meanings
> **See also:** Rule 1.5 — You can use words in a technical noun category
> **See also:** Rule 1.6 — Use non-approved words only as technical code nouns
> **See also:** Rule 1.7 — Do not use technical nouns as verbs
> **See also:** Rule 1.9 — Prefer short, clear technical nouns
> **See also:** Rule 1.10 — Use no slang, jargon, or regional terms
> **See also:** Rule 1.11 — Use one term per concept
> **See also:** Rule 1.12 — You can use verbs in a technical verb category
> **See also:** Rule 1.14 — Use American English spelling

---

## Grammar Notes

### The Authority Hierarchy for Technical Noun Selection

When more than one name exists for the same concept, choose the name from the most authoritative source. The authority hierarchy is:

1. **The source code** (class names, function names, file names, variable names, type names)
2. **The language specification** (keyword names, standard library names, built-in type names)
3. **The framework or library documentation** (API names, component names, hook names, configuration key names)
4. **The project glossary** (project-specific terms registered under Rule 1.5)
5. **The industry standard** (design pattern names, protocol names, algorithm names, architecture names)
6. **The company documentation** (internal system names, service names, team names)

When a conflict exists (for example, the source code calls it `DataStore` but the industry standard calls it `Repository`), use the higher-ranked source for code elements and the industry standard for conceptual explanations. Never mix names from different levels for the same concept in the same document.

> **STE:** The `DataStore` class provides the repository layer. It implements the Repository pattern from domain-driven design.

> *Explanation: `DataStore` (source code, level 1) is the code element name. "Repository pattern" (industry standard, level 5) is the conceptual name. The sentence uses both correctly by distinguishing them: one names the class, the other names the pattern.*

### Approved Technical Nouns as Modifiers

When you use the approved technical noun as a modifier (an adjective before another noun), the compound noun phrase inherits the approval status of the head noun. The modifier must be the approved technical noun — do not substitute a description as the modifier.

> **STE:** The `UserRepository` interface defines the database operations. (correct — `UserRepository` is the approved name, used as a modifier of "interface")
> **Non-STE:** The user storage interface defines the database operations. (incorrect — "user storage" is not the approved name)

> **STE:** The Observer pattern implementation uses a list of Observer instances. (correct — "Observer" is the approved pattern role name)
> **Non-STE:** The watcher pattern implementation uses a list of watcher objects. (incorrect — "watcher" is not the approved pattern name)

### Capitalization of Approved Technical Nouns

Follow the capitalization conventions of the source. Class names use PascalCase in most languages. Function names use camelCase in JavaScript and Java, snake_case in Python and Rust. Configuration keys use UPPER_SNAKE_CASE. Do not change the capitalization to match the surrounding sentence — the approved technical noun keeps its original form.

> **STE:** The `userService` instance calls the `findById` method. (correct — `userService` and `findById` keep their source code capitalization)
> **Non-STE:** The `UserService` instance calls the `FindById` method. (incorrect — changed capitalization; these are not the names in the source code)

### Approved Technical Nouns and the Definite Article

When you refer to an approved technical noun that is a unique entity (a specific class, a specific configuration key, a specific protocol), use the definite article "the." When you refer to the concept in general, omit the article.

> **STE:** The `UserController` handles the request. (specific class — use "the")
> **STE:** `UserController` is a common pattern in Spring Boot applications. (concept in general — no article)
> **Non-STE:** `UserController` handles the request. (missing article — `UserController` is a specific class in this context)

### Approved Names in Code Blocks vs. Prose

When the approved technical noun appears in a code block, it is part of the quoted text (Rule 1.5, category 10). When it appears in prose, it is a code-domain technical noun. In both cases, use the exact approved name. The formatting changes, but the name does not.

> **STE:** The `UserService.findById` method returns a `User` object — the approved names are identical in code blocks and prose:
> ```python
> const user = await UserService.findById(id);
> ```

> *Explanation: `UserService`, `findById`, and `User` appear in both the code block and the prose. The formatting changes (code block vs. inline code), but the names are identical. A reader who sees `UserService.findById` in the prose can find it in the code block and in the source code.*

---

## Summary Checklist

Use this checklist to check that your documentation obeys Rule 1.8:

1. Identify each concept that has a name in more than one place (codebase, glossary, industry standard).
2. Find the most authoritative source for each concept (source code > language spec > framework docs > glossary > industry standard > company docs).
3. Use the exact name from the most authoritative source. Do not paraphrase, abbreviate, or describe it.
4. If the codebase name differs from the industry name, mention both with clear context (codebase name for traceability, industry name for comprehension).
5. Define each acronym at its first use. Use only the acronym after the definition.
6. Keep the capitalization and spelling of the approved name exactly as it appears in the source.
7. Check that you did not use a description where an approved technical noun exists.
8. If the approved name changes during a refactor, use the new name. Mark the old name as DEPRECATED.
9. Make sure the same concept uses the same approved name throughout the document and across all project documentation.

---

## Distinction from Related Rules

Rule 1.8 is often confused with other rules because they all deal with word choice. Use this table to distinguish them:

| Situation | Which Rule Applies | Example |
|---|---|---|
| A word is not in the STE-Code dictionary, but it names a code concept | Rule 1.5 | "middleware" is a code-domain technical noun |
| A word is not in the dictionary and is not a code concept | Rule 1.6 | "utilize" is forbidden — use "use" |
| A code-domain technical noun is used as a verb | Rule 1.7 | "Cache the data" → "Put the data in the cache" |
| Two names exist for the same code concept — which to use? | **Rule 1.8** | "AccountController" vs. "account controller" |
| Two approved names exist — which is better? | Rule 1.9 | "UserRepository" vs. "UserDatabaseAccessObject" |
| An informal term names a standard concept | Rule 1.10 | "kicks off" → "starts" |
| The same concept has two different names in the same document | Rule 1.11 | Use "UserService" everywhere, not mixed with "UserManager" |

Rule 1.8 answers one question: "I know this is a technical noun — but which name should I use?" The answer is always: use the name from the most authoritative source.

---

<!-- a-sec1-rule1.9.md -->

# Rule 1.9 — When You Must Select a Technical Noun, Use One Which Is Short and Easy to Understand

> **Source:** Adapted from ASD-STE100 Issue 9
> **Source:** [master.md#sec1-rule1.9](ste-code/grouped/), Rule 1.9

## Original Rule

**Rule 1.9** When you must select a technical noun, use one which is short and easy to understand.

When there is no technical noun that is approved in your company, industry, or subject field, select one that is short (not more than three words) and easy to understand.

Example:

> **Non-STE:** Remove the four stainless steel pan head machine screws (10) that attach the metallic machined flange (15) to the front housing cover (20).
>
> **STE:** Remove the four screws (10) that attach the flange (15) to the cover (20).

In this example, it is sufficient to use the words "screws," "flange," and "cover." This is because these parts have index numbers, and the related illustration clearly identifies them. Differently, add one or two adjectives to the noun to help your reader understand.

## STE-Code Adaptation

**Rule 1.9** When you must select a code-domain technical noun, use one which is short and easy to understand.

When there is no code-domain technical noun that is approved in your project, company, industry, or subject field, select one that is short (not more than three words) and easy to understand.

Do not use long descriptive phrases when a shorter term is sufficient. If the context clearly identifies the item (for example, a code snippet, a diagram, or an API reference), use the shortest term that is unambiguous. If additional clarification is necessary, add one or two adjectives to the noun to help your reader understand.

### Examples

> *Adapted from spec pair:* Non-STE: Remove the four stainless steel pan head machine screws (10) that attach the metallic machined flange (15) to the front housing cover (20).  |  STE: Remove the four screws (10) that attach the flange (15) to the cover (20).

**Spec pair in code context.** The original ASD-STE100 example uses an index number (10) and an illustration to identify a physical part. In STE-Code, a line number and a code snippet do the same work.

```javascript
// client.js — line 42
async function fetchUtility(url) {
  const response = await fetch(url);
  return response.json();
}
```

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility function (line 42) to get the serialized JSON payload from the remote application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from the API endpoint.

This adapts the spec pair: "Remove the four stainless steel pan head machine screws (10) that attach the metallic machined flange (15) to the front housing cover (20)" becomes "Remove the four screws (10) that attach the flange (15) to the cover (20)." In the spec, the long descriptive phrase "stainless steel pan head machine screws" is reduced to "screws" because the index number (10) and the illustration identify the part. In STE-Code, the long phrase "asynchronous JavaScript XML HTTP request wrapper utility function" is reduced to "`fetchUtility` function" because the line number (42) and the code snippet identify the function. "JSON payload" becomes "JSON data" and "remote application programming interface endpoint" becomes "API endpoint" — both follow the spec principle of using the shortest unambiguous term.

## Code-Domain Explanation

Rule 1.9 addresses a common failure in code documentation: the use of excessively long noun phrases when a short term would be clearer. Documentation writers often believe that more words equal more precision. The opposite is usually true. Long noun phrases increase cognitive load. The reader must parse a chain of modifiers before reaching the head noun. Short terms reduce this load.

The rule is not an absolute command to use only one-word nouns. It is a directive to use the shortest term that is unambiguous in context. When the context already identifies the item — through a code reference, a line number, a diagram, or a preceding definition — the short term is sufficient. When the context does not identify the item, the rule permits adding one or two adjectives.

The three-word limit is a guideline, not a hard constraint. Exceptions exist for established technical terms that require more than three words (for example, "abstract syntax tree," "single page application," "continuous integration pipeline"). These multi-word terms are acceptable under Rule 1.5 (code-domain technical nouns) when they name a precise concept that cannot be shortened without losing meaning.

### Application by Documentation Type

**README files.** README documents introduce a project. They must convey the project's purpose, installation, and usage quickly. Long noun phrases in a README discourage readers. A README that says "the multi-platform containerized microservice orchestration and deployment management layer" loses the reader. Write "the Kubernetes cluster" instead. The shorter term is more specific and more recognizable.

**API documentation.** API docs describe endpoints, parameters, and return types. Each endpoint, parameter, and type already has a name. Do not repeat the name with a long descriptive phrase. An API doc that says "the user account profile information data transfer object parameter" is redundant when the parameter is named `UserProfileDTO`. Write "the `UserProfileDTO` parameter" and let the type definition provide the details.

**Docstrings and inline comments.** Docstrings appear directly above the code they describe. The code itself provides the ultimate context. A docstring that describes a function named `validateEmailAddress` does not need to say "this function validates an electronic mail address string against a regular expression pattern that implements the RFC 5322 specification for internet message format addresses." Write "Validate an email address against RFC 5322." The function signature, the regex pattern, and the RFC reference are all visible in the code.

**Commit messages.** Commit messages are constrained by convention to a short subject line (50-72 characters) and an optional body. Long noun phrases in the subject line force wrapping or truncation. A commit message subject that says "Refactor the asynchronous task processing and scheduling subsystem initialization sequence" exceeds typical length limits. Write "Refactor the task scheduler initialization." The body can provide additional detail.

**Error messages.** Error messages appear in logs, terminals, and alert systems. They are often truncated by display tools. Long noun phrases in error messages waste the reader's time and increase the chance that critical information is cut off. An error message that says "The remote procedure call connection handshake negotiation to the primary database cluster node failed" should be "Connection to the primary database node failed." The short version tells the reader what failed and which component is affected.

**CLI help text and man pages.** Command-line help text has limited horizontal space (typically 80 columns). Long noun phrases cause line wrapping that makes help text unreadable. Use the shortest term that identifies the concept. A flag description that says "Specifies the maximum number of concurrent parallel worker thread processes" should be "Maximum number of worker threads."

### Worked Documentation-Type Examples

The following pairs show the same principle applied across each documentation type. Each Non-STE example carries a long noun phrase; each STE example uses the shortest unambiguous term and lets the surrounding code or structure carry the detail.

**README — project one-liner.**

> **Non-STE:** This is a highly extensible, plugin-based, asynchronous task execution and job scheduling framework toolkit that you can embed inside any long-running backend service process.
>
> **STE:** TaskRunner is a job scheduler. Embed it in any backend service.

```markdown
# TaskRunner
A job scheduler for background tasks. Embed it in your service.

## Install
npm install task-runner
```

**API documentation — response field.**

> **Non-STE:** The response body contains a single user account profile information resource object that includes the unique identifier string, the canonical display name text, and the timestamp of the most recent successful authentication event.
>
> **STE:** The response is a `User` object with `id`, `displayName`, and `lastLoginAt`.

```json
{
  "id": "u_8f2c",
  "displayName": "Jane Doe",
  "lastLoginAt": "2026-07-30T09:14:00Z"
}
```

**Docstring — class summary.**

> **Non-STE:** This is the central application-wide singleton instance manager component that is responsible for the creation, configuration, and lifecycle coordination of all long-lived background worker process objects.
>
> **STE:** The `WorkerManager` starts and stops background workers.

```python
class WorkerManager:
    """The WorkerManager starts and stops background workers."""

    def start(self, worker: Worker) -> None:
        ...
```

**Commit message — subject line.**

> **Non-STE:** Implement the comprehensive end-to-end encrypted credential storage and retrieval subsystem together with its corresponding automated test suite.
>
> **STE:** Add encrypted credential storage with tests.

```text
git commit -m "Add encrypted credential storage with tests"
```

**Error message — log line.**

> **Non-STE:** The background asynchronous file synchronization daemon process encountered an unrecoverable input/output failure while attempting to write the cached user preference configuration data file to the persistent local disk volume.
>
> **STE:** Sync failed: could not write the config file to disk.

```python
logger.error("Sync failed: could not write the config file to disk")
```

**CLI help text — flag description.**

> **Non-STE:** Specifies the maximum permitted quantity of simultaneously executing concurrent parallel worker subprocess threads that the application is permitted to spawn and manage for the purpose of processing items from the background job queue.
>
> **STE:** Maximum number of worker threads for the job queue.

```python
parser.add_argument(
    "--max-workers",
    type=int,
    default=4,
    help="Maximum number of worker threads for the job queue.",
)
```

### The Context Principle

The core insight of Rule 1.9 is that context permits brevity. The original ASD-STE100 example demonstrates this: index numbers and illustrations provide context, so short nouns ("screws," "flange," "cover") are sufficient. In code documentation, equivalent context sources include:

- **Code references:** A line number, a function name, a class name, or a file path identifies the item unambiguously. Use the short term plus the reference.
- **Diagrams and figures:** An architecture diagram that labels components with short names makes long descriptions unnecessary in the accompanying text.
- **Preceding definitions:** If you define a term at first use ("the authentication service, called AuthService"), use the short name for all subsequent references.
- **API specifications:** An OpenAPI spec or a protobuf definition that fully describes a type makes long descriptions in prose redundant. Reference the type by name.
- **Code snippets:** When a code snippet follows the prose, the snippet provides full context. The prose only needs to introduce the snippet, not duplicate its content.

When none of these context sources are available, add one or two adjectives to the noun. The adjectives must be necessary for disambiguation. Do not add adjectives that describe properties already visible in the context.

### The Three-Word Limit: Rationale and Exceptions

The three-word limit is derived from the original ASD-STE100 specification, which states that a technical noun must be "short (not more than three words)." The limit reflects cognitive research: readers can hold approximately three to four chunks of information in working memory. A noun phrase of more than three words exceeds this capacity and forces the reader to re-read.

Exceptions to the three-word limit:

1. **Established technical terms.** Terms such as "continuous integration pipeline" (3 words), "single sign-on provider" (3 words), and "abstract syntax tree" (3 words) are at the limit. Terms such as "public key infrastructure certificate" (4 words) exceed the limit but are standard in the security domain. Use the established term even if it exceeds three words. Do not invent a shorter form that the community does not use.
2. **Framework and tool names.** Names such as "GitHub Actions workflow," "Amazon Web Services Lambda," and "Google Cloud Platform" exceed three words but are proper nouns. Use them as given. Do not abbreviate unless the abbreviation is a recognized technical noun (for example, "AWS Lambda").
3. **Fully qualified type names.** In strongly typed languages, fully qualified names can be long (for example, `com.example.project.module.SubComponent`). Use the short name (`SubComponent`) after the first reference, or use the language's import/alias mechanism to refer to the type.
4. **When shortening causes ambiguity.** If shortening a four-word phrase to three words creates ambiguity between two different concepts, keep the four-word phrase. Clarity overrides brevity.

### Long Phrase to Short Form Reference Table

Use this table as a quick lookup when you find a long noun phrase in your documentation. The STE column gives the shortest unambiguous form; the trigger shows what context makes the short form safe.

| Long code-domain phrase | Short STE form | Context that permits the short form |
|---|---|---|
| asynchronous JavaScript XML HTTP request wrapper utility function | fetch utility | line number + code snippet |
| serialized JSON payload from the remote application programming interface endpoint | JSON data from the API endpoint | field name + type definition |
| user account profile information data transfer object | `UserProfileDTO` | the parameter is already named |
| relational database management system server instance | database | port number + "primary" |
| multi-platform containerized microservice orchestration and deployment management layer | Kubernetes cluster | diagram or README title |
| dependency injection inversion of control container | DI container | preceding definition of DI |
| mutual exclusion lock primitive with timeout-bounded acquisition | mutex | class name in the code |
| configuration, settings, and options parameters object | `Config` object | the object is named `Config` |
| dynamically allocated resizable contiguous memory region management utility | dynamic array | the type is declared |
| horizontal pod autoscaling controller with CPU utilization threshold | `HorizontalPodAutoscaler` resource | the YAML `kind` field |

## Paradigm-Specific Guidance

### Object-Oriented Paradigm (Java, C++, C#, Python classes)

Object-oriented documentation often describes class hierarchies with long inheritance chains. Writers describe a class as "the abstract base repository implementation class that extends the generic type-parameterized CRUD repository interface." This phrase buries the class name under six modifiers.

**Practice:** Use the class name. The reader can inspect the class definition for its inheritance chain, type parameters, and implemented interfaces. Write "the `UserRepository` class." If the inheritance is relevant to the discussion, state it in a separate sentence: "`UserRepository` extends `BaseRepository<User>`."

**Before:** The concrete factory method implementation class instantiates the appropriate data access object implementation based on the runtime configuration profile.
**After:** The `DaoFactory` class creates the correct DAO implementation for the active configuration profile.

```java
// The DaoFactory class creates the correct DAO implementation for the active configuration profile.
public class DaoFactory {
    public UserDao createUserDao(ConfigProfile profile) {
        return new JdbcUserDao(profile.getDataSource());
    }
}
```

**Before:** The dependency injection inversion of control container manages the lifecycle of the singleton-scoped service provider instances.
**After:** The DI container manages the lifecycle of singleton services.

```python
# The DI container manages the lifecycle of singleton services.
container = Container()
container.register(UserService, scope="singleton")
```

In the second example, "DI" is a recognized abbreviation (category 16, Rule 1.5). "IoC" is removed because "DI container" already implies the concept. "Singleton-scoped service provider instances" becomes "singleton services" — the scope and role are clear from the context of DI documentation.

### Functional Paradigm (Haskell, Elixir, Clojure, Rust)

Functional programming documentation often describes transformations with long noun phrases that trace the entire data-flow chain. A writer describes a value as "the result of applying the partially applied curried function composition pipeline to the input list after mapping and filtering." The phrase describes the entire computation instead of naming the result.

**Practice:** Name the result. Use a short noun phrase that identifies what the value represents, not how it was computed. The computation is visible in the code.

**Before:** The monomorphized iterator adapter chain with lazy evaluation semantics produces a collection of transformed elements.
**After:** The iterator produces a transformed collection.

**Before:** The higher-order function that takes a binary operation and an initial accumulator value and returns a function that reduces a foldable data structure to a single value.
**After:** The fold function. It reduces a collection to a single value.

```haskell
-- The fold function. It reduces a collection to a single value.
sumValues :: [Int] -> Int
sumValues = foldl (+) 0
```

In the second example, "fold" is a standard algorithmic term (category 7). The long description duplicates what every functional programmer already knows. Use the standard term.

**Before:** The discriminated union algebraic data type with exhaustive pattern matching guarantees.
**After:** The enum type. Pattern matching covers all variants.

```rust
// The enum type. Pattern matching covers all variants.
enum Status {
    Active,
    Suspended,
    Closed,
}
```

"Enum" is a data type term (category 4). "Discriminated union" and "algebraic data type" are synonyms in this context. Choose one and use it consistently (Rule 1.11). Do not use both in the same noun phrase.

### Procedural Paradigm (C, Go, Bash)

Procedural documentation often describes functions with long noun phrases that list every parameter, return value, and side effect. A C function description says "the function that accepts a pointer to a null-terminated character array and an unsigned integer representing the maximum buffer size and returns an integer status code indicating success or failure." This phrase describes the entire function signature.

**Practice:** Name the function. Describe its purpose in a short sentence. Let the function signature carry the type information.

**Before:** The variadic formatted output to file descriptor function with thread-safe internal buffering.
**After:** The `fprintf` function. It writes formatted output to a file descriptor.

**Before:** The dynamically allocated resizable contiguous memory region management utility.
**After:** The dynamic array. It grows as you add elements.

```go
// The dynamic array. It grows as you add elements.
type DynamicArray struct {
    items []int
}

func (d *DynamicArray) Append(value int) {
    d.items = append(d.items, value)
}
```

In the second example, "dynamic array" is a standard data structure term (category 4). The long phrase "dynamically allocated resizable contiguous memory region management utility" describes implementation details that are not needed for understanding the concept.

**Before:** The mutual exclusion lock primitive with timeout-bounded acquisition and deadlock detection.
**After:** The mutex. It has a timeout and deadlock detection.

```go
// The mutex. It has a timeout and deadlock detection.
mu := sync.Mutex{}
if mu.TryLock() {
    defer mu.Unlock()
}
```

"Mutex" is a computer science term (category 16). The additional features (timeout, deadlock detection) are described in a separate sentence, not embedded in the noun phrase.

### Declarative Paradigm (SQL, Terraform, Kubernetes YAML)

Declarative documentation often describes resources with long noun phrases that enumerate every attribute. A Terraform doc says "the Amazon Web Services Elastic Compute Cloud virtual machine instance resource with attached elastic block store volume and security group configuration." This phrase embeds the entire resource configuration.

**Practice:** Name the resource type. Describe the configuration in bullet points or a table. The declarative code itself is the ultimate reference.

**Before:** The Kubernetes horizontal pod autoscaling controller with CPU utilization metric threshold and minimum and maximum replica count bounds.
**After:** The `HorizontalPodAutoscaler` resource. It scales pods based on CPU utilization. Set the minimum and maximum replica counts.

```yaml
# The HorizontalPodAutoscaler resource. It scales pods based on CPU utilization.
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-hpa
spec:
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
```

**Before:** The Structured Query Language parameterized query with multiple table joins, aggregate functions, grouping clauses, and sorted result set.
**After:** The parameterized query. It joins the `users` and `orders` tables and groups results by region.

```sql
-- The parameterized query. It joins the users and orders tables and groups results by region.
SELECT region, COUNT(*) AS orders
FROM users
JOIN orders ON orders.user_id = users.id
GROUP BY region
ORDER BY orders DESC;
```

In the second example, the long phrase describes the SQL structure. The short description states what the query does. The SQL code itself shows the joins, aggregates, and sorting.

### Systems Programming (Rust ownership, C memory management)

Systems documentation often describes memory operations with long noun phrases that explain every safety guarantee. A Rust doc says "the compile-time checked reference that enforces the borrowing rules and prevents simultaneous mutable and immutable access to the same memory location." This phrase explains what the borrow checker does, not what the reference is.

**Practice:** Use the short term ("reference," "borrow," "lifetime"). The Rust compiler enforces the guarantees. Documentation describes what the programmer controls, not what the compiler prevents.

**Before:** The affine type system linear resource ownership tracking mechanism that prevents use-after-move errors at compile time.
**After:** The ownership system. It prevents use-after-move errors.

**Before:** The dynamically sized slice reference type with bounds checking that prevents out-of-bounds memory access at runtime.
**After:** The slice reference. Bounds checks prevent out-of-bounds access.

```rust
// The slice reference. Bounds checks prevent out-of-bounds access.
fn first(bytes: &[u8]) -> Option<u8> {
    bytes.first().copied()
}
```

In both examples, the safety mechanism (ownership, bounds checking) is described in a separate sentence. The noun phrase names the concept. The explanation follows.

## Extended Examples

### Example Group 1: README Project Description

A README introduces a library. The code block after the prose gives the reader the full context, so the prose does not need to name every internal detail.

````markdown
# FetchKit

A small client for HTTP requests.

## Install
npm install fetchkit

## Use
```javascript
import { FetchKit } from "fetchkit";

const client = new FetchKit();
const users = await client.getJson("/api/users");
```
````

> **Non-STE:** This is a high-performance, event-driven, non-blocking I/O model JavaScript runtime environment built on Chrome's V8 JavaScript engine that uses an asynchronous, single-threaded event loop architecture for building scalable network applications.
>
> **STE:** FetchKit is an HTTP client. It uses an event-driven, non-blocking I/O model. Use it to build scalable network applications.

- **Principle applied:** P9 (use short technical nouns: "FetchKit" is 1 word, "HTTP client" is 2 words)
- **Explanation:** The non-STE version is a 42-word noun phrase that embeds architecture details, the engine name, and the use case. The STE version names the technology in one or two words, then explains the architecture and use case in separate sentences. The reader can absorb each piece of information independently. This follows the spec principle: "screws" (one word) replaces "stainless steel pan head machine screws" (six words). The context — the README title, the installation section, the code example — makes the short term sufficient.

### Example Group 2: API Documentation Parameter Description

The endpoint already names the fields in its request contract. The prose only needs to point the reader to that contract.

````http
POST /v1/users
Content-Type: application/json

{
  "emailAddress": "jane@example.com",
  "displayName": "Jane Doe",
  "subscribeToNewsletter": false
}
````

> **Non-STE:** The request body must contain a JSON object with a required string field named "emailAddress" that must match the standard internet electronic mail address format as defined by RFC 5322, an optional string field named "displayName" with a maximum length of 100 Unicode characters, and a required boolean field named "subscribeToNewsletter" that defaults to false if not provided.
>
> **STE:** The request body is a JSON object with these fields:
> - `emailAddress` (string, required) — a valid email address
> - `displayName` (string, optional, max 100 characters)
> - `subscribeToNewsletter` (boolean, optional, default: `false`)

- **Principle applied:** P9 (use short technical nouns: each field name is a one-word or two-word noun)
- **Explanation:** The non-STE version is a single 86-word sentence that embeds field names, types, constraints, defaults, and a reference to an RFC. The STE version uses a bulleted list. Each field is described with its name, type, and constraint. The RFC reference is removed because the field name "emailAddress" and the constraint "a valid email address" are sufficient for the API documentation. The API consumer can look up RFC 5322 if they need the full specification. This follows the spec principle: the field name is like the index number (10) in the original example — it identifies the item unambiguously, so a short description is sufficient.

### Example Group 3: Docstring for a Function

The function signature and body show the types and the work. The docstring states the action and the result.

```python
def create_user(email_address, display_name=None, subscribe=False):
    """Create and return a new User instance with the given dependencies.

    Args:
        email_address: Email for the new account.
        display_name: Optional display name.
        subscribe: Opt in to the newsletter.
    """
    user = User(email=email_address, name=display_name)
    user.newsletter = subscribe
    user.save()
    return user
```

> **Non-STE:** This public static factory method constructs and returns a newly created, fully initialized, thread-safe instance of the UserService class with all of its required collaborator dependencies injected and its internal state properly configured for the current runtime environment.
>
> **STE:** Create and return a new `User` instance with the given dependencies.

- **Principle applied:** P9 (use short technical nouns: "User instance" is 2 words, "dependencies" is 1 word)
- **Explanation:** The non-STE version is a 40-word noun phrase that describes the method's visibility ("public"), its nature ("static factory"), its return behavior ("newly created"), its thread safety, its initialization state, and its configuration. The STE version states the action ("Create and return") and the result ("a new User instance"). The code signature shows the parameters. The class documentation describes thread safety. The docstring does not need to repeat information that the code already conveys. This follows the spec principle: the function signature is like the illustration in the original example — it provides context that makes a long description unnecessary.

### Example Group 4: Commit Message Subject Line

The subject line is short. The body can carry detail. Use a recognized abbreviation (JWT) instead of the expanded form.

```text
git commit -m "Refactor auth middleware: extract JWT validation and role resolution into separate utilities"
```

> **Non-STE:** Refactor the authentication and authorization middleware layer to extract the JSON Web Token validation and user permission role resolution logic into separate composable utility functions.
>
> **STE:** Refactor auth middleware: extract JWT validation and role resolution into separate utilities.

- **Principle applied:** P9 (use short technical nouns: "auth middleware" is 2 words, "JWT validation" is 2 words, "role resolution" is 2 words)
- **Explanation:** The non-STE version is a 28-word subject line that exceeds typical commit message length limits (50-72 characters recommended). The STE version is 13 words with a clear structure: action (refactor), target (auth middleware), colon, detail (extract X and Y into Z). "Authentication and authorization" becomes "auth" — the abbreviation is recognized in the codebase. "JSON Web Token" becomes "JWT" — the acronym is an approved technical noun (category 19). "User permission role resolution logic" becomes "role resolution" — the context (auth middleware) makes "user permission" redundant. This follows the spec principle: just as "stainless steel pan head machine screws" becomes "screws," the commit message uses the shortest term that the project context makes unambiguous.

### Example Group 5: Error Message

The error message is the text a reader sees in a log or terminal. Keep it short so display tools do not cut it off.

```python
try:
    connect("192.168.1.100", 5432, timeout=30)
except TimeoutError:
    raise ConnectionError(
        "Connection to the primary database at 192.168.1.100:5432 "
        "timed out after 30 seconds"
    )
```

> **Non-STE:** The operation to establish a connection to the primary relational database management system server instance located at the network address 192.168.1.100 on the default Transmission Control Protocol port number 5432 has failed due to a network timeout condition after waiting for the configured connection timeout duration of 30 seconds.
>
> **STE:** Connection to the primary database at 192.168.1.100:5432 timed out after 30 seconds.

- **Principle applied:** P9 (use short technical nouns: "primary database" is 2 words, "timed out" is a technical verb per P12)
- **Explanation:** The non-STE version is a 55-word sentence that embeds the database type ("relational database management system"), the server role ("primary"), the protocol ("Transmission Control Protocol"), the default port ("5432"), the failure type ("network timeout condition"), and the duration. The STE version is a 13-word sentence that conveys the same information: what failed (connection), where (192.168.1.100:5432), what happened (timed out), and when (after 30 seconds). The protocol is implied by the port number and the term "database." The database type is implied by "primary" (which implies a replica set, specific to certain databases). The error message reader needs to know what to fix, not what every acronym expands to. This follows the spec principle: the short term is sufficient because the context (a database connection error) identifies the components.

### Example Group 6: CLI Help Text

The flag name carries the concept; the help string only needs to state the limit and the target.

```python
parser.add_argument(
    "--max-workers",
    type=int,
    default=4,
    help="Maximum number of worker threads for the job queue.",
)
```

> **Non-STE:** Specifies the maximum permitted quantity of simultaneously executing concurrent parallel worker subprocess threads that the application is permitted to spawn and manage for the purpose of processing items from the background job queue.
>
> **STE:** Maximum number of worker threads for the job queue.

- **Principle applied:** P9 (use short technical nouns: "worker threads" is 2 words, "job queue" is 2 words)
- **Explanation:** The non-STE version is a 36-word description for a single flag. It uses synonyms piled together ("simultaneously executing concurrent parallel") and redundant permissions language ("permitted to spawn and manage"). The STE version is 9 words. "Maximum" implies the flag sets an upper bound. "Worker threads" names the resource. "Job queue" names the target. The reader does not need to be told that threads are "subprocess threads" or that they "process items" from a queue — these are inherent to the concepts of "worker threads" and "job queue." This follows the spec principle: reduce to the shortest term that is unambiguous in the program's context.

### Example Group 7: Configuration File

A configuration file already states the keys and values. The inline comment only needs to name the purpose in one short phrase; the key name carries the rest.

```yaml
# worker settings
max_workers: 8          # maximum number of worker threads
queue: "jobs"           # the job queue to read from
retry_limit: 3          # attempts before a task fails
```

> **Non-STE:** The maximum permitted quantity of simultaneously executing concurrent parallel worker subprocess threads that the application is permitted to spawn and manage for processing items from the background job queue.
>
> **STE:** Maximum number of worker threads for the job queue.

- **Principle applied:** P9 (use short technical nouns: "worker threads" is 2 words, "job queue" is 2 words)
- **Explanation:** The non-STE version is the same 36-word phrase repeated as a config comment. In a config file, the key `max_workers` already names the setting and the value `8` states the limit. A nine-word comment is all the prose needs. Do not copy the long phrase into the comment — the key and value are the context.

### Example Group 8: Test Description

A test already names the function under test and the assertion. The test name and the assertion body carry the detail; the comment only states intent in the shortest form.

```python
def test_fetch_utility_returns_json():
    # the fetch utility returns parsed JSON from the API endpoint
    result = fetch_utility("https://api.example.com/users")
    assert result["id"] == "u_8f2c"
```

> **Non-STE:** Verify that the asynchronous JavaScript XML HTTP request wrapper utility function successfully retrieves and deserializes the serialized JSON payload from the remote application programming interface endpoint into a native object structure.
>
> **STE:** The fetch utility returns parsed JSON from the API endpoint.

- **Principle applied:** P9 (use short technical nouns: "fetch utility" is 2 words, "API endpoint" is 2 words)
- **Explanation:** The non-STE version is a 26-word test description that embeds every implementation detail. The STE version reuses the shortest terms already established in this rule ("fetch utility," "API endpoint") and states the one behavior the test checks. The function name `test_fetch_utility_returns_json` and the `assert` line identify the subject and the expectation, so the comment does not need to repeat them as a long phrase.

## Edge Cases

### Edge Case 1: When the Short Term Is Less Well-Known Than the Long Term

Some short technical nouns are obscure. A documentation writer might use "AST" (2 words when expanded: "abstract syntax tree") because it is short, but a junior developer may not know the acronym. The rule says to use the term that is "easy to understand," not just short.

**Resolution:** Use the expanded form at first use: "abstract syntax tree (AST)." Use "AST" for all subsequent references. If the audience is expected to know the acronym (for example, in a compiler documentation context), use "AST" directly. The ease-of-understanding test is: would a developer with one year of experience in this domain understand the term? If yes, the short term is acceptable. If no, expand on first use.

```python
# Before: walk the AST to find unused bindings
# After (first use in a general document):
# Walk the abstract syntax tree (AST) to find unused bindings.
# Later in the same document: prune the AST.
```

### Edge Case 2: When a Framework Name Is Also a Short Word

Frameworks with short, common-word names (React, Vue, Go, Rust, Next, Nest, Swift, Elm) create ambiguity. In a sentence such as "Use React to react to user input," the word "React" appears twice with different meanings. The short word is ambiguous.

**Resolution:** Use the framework name as a modifier: "the React framework" or "the Go language." This adds one word and resolves the ambiguity. After the first use, the bare name is acceptable if the context is clear. Do not create a new abbreviation to avoid the ambiguity — "Rkt" for "React" is not a standard term and violates Rule 1.8 (use standard technical nouns).

### Edge Case 3: When the Codebase Uses Long Names Internally

Some codebases use long, descriptive class names and function names by convention (for example, Java enterprise applications with names like `AbstractUserAuthenticationProviderFactoryBean`). Rule 1.9 says to use short terms, but the codebase name is the approved technical noun (Rule 1.8). The rules appear to conflict.

**Resolution:** Rule 1.8 takes precedence for names that are defined in the codebase. Use the codebase name as given. Rule 1.9 applies to the prose that surrounds the name. You can refer to "the factory bean" (short) in prose after introducing the full name: "The `AbstractUserAuthenticationProviderFactoryBean` (the factory bean) creates authentication providers." Do not rename the class in the code or in references — only in the surrounding prose.

### Edge Case 4: When Shortening Creates a Homonym

In some domains, a short term can refer to two different concepts. For example, "cache" can mean a hardware CPU cache or a software in-memory cache. "Pool" can mean a thread pool, a connection pool, or an object pool. If shortening "database connection pool" to "pool" could cause confusion with "thread pool" in the same document, the short term is not unambiguous.

**Resolution:** Keep the disambiguating modifier. "Connection pool" and "thread pool" are both two-word phrases (within the three-word limit). The one-word form "pool" is acceptable only when the document discusses exactly one kind of pool throughout. If the document discusses both, always use the two-word form. Context determines sufficiency.

### Edge Case 5: Generated Documentation and Automated Summaries

Tools such as JSDoc, Sphinx, and godoc generate documentation from source code. These tools often produce verbose output that includes the full type signature, all parameters, and all return values in a single block. The generated text may violate the three-word limit for noun phrases because it mechanically reproduces the code structure.

**Resolution:** Generated documentation is exempt from Rule 1.9 for the auto-generated portions (same principle as Edge Case 4 in Rule 1.5). However, any human-written summary, description, or comment within the generated documentation must follow Rule 1.9. When writing a JSDoc `@description` tag or a Python docstring summary line, apply the rule: use the shortest term that is unambiguous.

```javascript
/**
 * The rate limiter uses a token bucket algorithm backed by Redis.
 * @param {number} maxTokens - Maximum number of tokens.
 */
class RateLimiter {}
```
The `@description`-equivalent summary ("The rate limiter uses a token bucket algorithm backed by Redis") uses short terms even though the generated parameter table below it is mechanical.

## Cross-References

- **Rule 1.1 (Approved Words):** When you shorten a noun phrase, replace non-approved words with approved words from the dictionary. For example, "leverage the authentication mechanism" becomes "use the auth service" — "leverage" is replaced with "use" (Rule 1.1), and "authentication mechanism" is shortened to "auth service" (Rule 1.9). The two rules work together.
- **Rule 1.5 (Technical Code Nouns):** Rule 1.5 defines which terms are permissible as code-domain technical nouns. Rule 1.9 applies after Rule 1.5: once you have identified a permissible technical noun, select the shortest form of it. "Application programming interface" is a technical noun under category 19; Rule 1.9 says to use "API."
- **Rule 1.6 (Non-Approved Words as Technical Nouns):** Rule 1.6 forbids non-approved words except as technical nouns. Rule 1.9 applies to the technical nouns that Rule 1.6 permits. A technical noun that passes Rule 1.6 must also pass Rule 1.9: it must be short and easy to understand.
- **Rule 1.8 (Standard Technical Nouns):** Rule 1.8 requires you to use the technical noun that is approved in your project or industry. Rule 1.9 says to use the shortest form of that approved noun. When the industry standard is a long form ("Transport Layer Security"), use the standard short form if one exists ("TLS"). Do not invent a non-standard short form ("TransSec").
- **Rule 1.10 (No Slang or Jargon):** Rule 1.10 forbids slang and jargon as technical nouns. Rule 1.9 reinforces this: a short slang term ("repo" for "repository") may seem to satisfy the shortness requirement, but it fails the "easy to understand" test for readers outside the community. Use the standard short form ("repository") or a recognized abbreviation.
- **Rule 1.11 (One Term per Concept):** Rule 1.11 requires consistency. When you shorten a technical noun under Rule 1.9, use the same shortened form everywhere in the document. Do not use "auth service" in one paragraph and "authentication module" in the next for the same component. Choose one short form and apply it consistently.
- **Rule 1.13 (Do Not Use Technical Verbs as Nouns):** Rule 1.13 forbids using verbs as nouns. A common violation occurs when writers shorten a noun phrase by converting a verb to a noun: "the deploy" instead of "the deployment process." Rule 1.9 does not permit this. The short form must be a noun, not a verb used as a noun.
- **Rule 1.14 (American English Spelling):** When a short form has both American and British spellings, use the American spelling. "Initialize" (American) not "initialise" (British). "Color" not "colour." This applies to all forms: full nouns, shortened nouns, and adjectives.

## Grammar Notes

### The Structure of Long Noun Phrases in Code Documentation

The original ASD-STE100 specification identifies the "noun cluster" as the primary source of long noun phrases. A noun cluster is a sequence of nouns and adjectives that all modify the final head noun. In code documentation, noun clusters follow predictable patterns:

**Pattern 1: Stacked Modifiers.** Writers stack multiple modifiers before the head noun: "the asynchronous event-driven non-blocking I/O JavaScript runtime environment." Each modifier adds a property. The reader must hold all modifiers in memory until reaching the head noun "environment."

**Correction:** Move modifiers into a separate clause or sentence. "The JavaScript runtime uses an asynchronous, event-driven, non-blocking I/O model."

**Pattern 2: Embedded Type Information.** Writers embed type information into the noun phrase: "the `Promise<Array<User>>` typed asynchronous function return value." The type is already visible in the code signature.

**Correction:** Name the concept, not the type. "The function returns a promise that resolves to an array of users."

**Pattern 3: Embedded Implementation Details.** Writers embed how something works into what it is called: "the Redis-backed distributed rate-limiting token bucket algorithm implementation." The implementation detail (Redis-backed, token bucket algorithm) is supplementary.

**Correction:** Separate the name from the implementation. "The rate limiter uses a token bucket algorithm backed by Redis."

**Pattern 4: Synonym Chains.** Writers use multiple synonyms to ensure they cover every possible interpretation: "the configuration, settings, and options parameters object." If the object is named `Config`, all three nouns refer to the same thing.

**Correction:** Choose one term. Use it consistently. "The `Config` object."

### Adjectives and the Three-Word Limit

The rule permits one or two adjectives when necessary for disambiguation. The adjectives must serve a purpose. They must distinguish the noun from other nouns in the same context. Adjectives that do not add disambiguating information are "noise adjectives" and must be removed.

**Noise adjective:** "the configurable application settings object" — All settings objects are configurable. The adjective adds no information.

**Disambiguating adjective:** "the production application settings object" — In a context where production, staging, and development settings all exist, "production" disambiguates.

**Noise adjective:** "the secure HTTPS protocol" — HTTPS is secure by definition.

**Disambiguating adjective:** "the legacy HTTPS endpoint" — In a context where old and new endpoints coexist, "legacy" disambiguates.

When you add an adjective, add exactly one. If the noun phrase reaches three words (adjective + adjective + noun), verify that both adjectives are necessary. If one can be removed without creating ambiguity, remove it.

### The Role of Abbreviations and Acronyms

Abbreviations and acronyms are the most direct application of Rule 1.9 in code documentation. The long form is a technical noun (permitted by Rule 1.5). The abbreviation is the short form (permitted by Rule 1.9). The decision to abbreviate depends on audience familiarity:

- **Universal abbreviations:** API, JSON, SQL, HTML, HTTP, URL, DNS, TCP, TLS, CPU, RAM, SSD. These are understood by all professional developers. Use the abbreviation on first reference. Expansion is optional.
- **Domain-specific abbreviations:** JWT (JSON Web Token), CORS (Cross-Origin Resource Sharing), ORM (Object-Relational Mapping), SPA (Single Page Application), SSR (Server-Side Rendering). These are understood within specific domains. Expand on first use in documents that serve a general audience. Use bare in documents that serve the domain audience.
- **Project-specific abbreviations:** Internal abbreviations that are defined in the project glossary. Expand on first use in every document. The abbreviation is acceptable only after it has been defined.

Do not create new abbreviations to satisfy Rule 1.9. An abbreviation is a word that the community recognizes. An abbreviation you invent today is a word nobody recognizes. It fails the "easy to understand" criterion.

### Shortening Without Losing Precision

The most common objection to Rule 1.9 is that shortening a noun phrase loses precision. This objection misunderstands the role of context. Precision comes from the combination of the noun phrase and its context. A long noun phrase in isolation is precise. A short noun phrase in context is equally precise and easier to read.

Consider the original ASD-STE100 example again. "Stainless steel pan head machine screws" is more precise in isolation than "screws." But in context — the illustration labels the screws, the index number (10) identifies them, the procedure step says "remove" — "screws" is precise enough. The precision lives in the context, not the noun phrase.

The same principle applies to code documentation. The code, the API spec, the diagram, and the preceding text all provide context. The noun phrase does not need to carry all the information alone. Trust the context. Write the short term.

## Practical Application: Documentation Review Checklist

Use this checklist when reviewing code documentation for Rule 1.9 compliance:

1. Identify every noun phrase of four or more words. Is there a shorter form?
2. For each long noun phrase, check if the context already identifies the item. Does a code reference, diagram, or preceding definition make the long form unnecessary?
3. If the context identifies the item, replace the long phrase with the shortest unambiguous form.
4. If the context does not identify the item, reduce the phrase to three words or fewer by removing noise adjectives and embedded implementation details.
5. Move removed details into separate sentences. One detail per sentence.
6. Check that every adjective in the shortened phrase serves a disambiguating purpose. Remove noise adjectives.
7. Verify that the shortened form is a recognized term (Rule 1.8), not a newly invented abbreviation.
8. Verify that the same shortened form is used consistently throughout the document (Rule 1.11).
9. For abbreviations, expand on first use unless the abbreviation is universal.
10. Read the shortened phrase aloud. Is it easy to understand? If not, the phrase is too short. Add one disambiguating adjective.

NOTE: This checklist is a guide. Professional judgment is always necessary when deciding between brevity and clarity. When the two conflict, clarity wins.

> **See also:** Rule 1.1 — Use Approved Words
> **See also:** Rule 1.5 — Use Approved Technical Nouns for Your Subject Field
> **See also:** Rule 1.6 — Use Non-Approved Words Only as Technical Nouns
> **See also:** Rule 1.8 — Use the Standard Technical Noun
> **See also:** Rule 1.10 — Do Not Use Slang or Jargon
> **See also:** Rule 1.11 — Use One Term for One Concept
> **See also:** Rule 1.13 — Do Not Use Technical Verbs as Nouns
> **See also:** Rule 1.14 — Use English (American) Spelling
