oborchers/abbreviation-policy

Full Words by Default, Abbreviations by Exception

Every abbreviation is a tax on the reader. The writer saves a few keystrokes; every future reader pays the cost of decoding. Modern editors autocomplete. Modern screens are wide. Modern codebases are searched, not memorized. There is no defensible reason to abbreviate an identifier unless the abbreviation is more widely recognized than the full word. url is clearer than uniformResourceLocator. btn is not clearer than button. This is the line, and it is not negotiable.

The Abbreviation Decision Framework

Before using any abbreviation, apply this test in order:

1. Is it on the universally understood list? Use it. id, url, http -- everyone knows these.
2. Would a new hire need to ask what it means? Spell it out. txMgr for "transaction manager" fails this test.
3. Is it in your project's abbreviation registry? Use it, but only if the registry exists and is maintained.
4. None of the above? Use the full word. Always.

The burden of proof is on the abbreviation. Full words are correct by default.

Universally Understood Abbreviations

These abbreviations are approved for use in any codebase without documentation. They are more recognizable than their expanded forms.

| Abbreviation | Meaning | Context | |-------------|---------|---------| | id | Identifier | Any | | url | Uniform Resource Locator | Any | | http / https | Hypertext Transfer Protocol | Any | | api | Application Programming Interface | Any | | db | Database | Any | | sql | Structured Query Language | Any | | html | HyperText Markup Language | Any | | css | Cascading Style Sheets | Any | | json | JavaScript Object Notation | Any | | xml | Extensible Markup Language | Any | | config | Configuration | Any | | auth | Authentication / Authorization | Any | | admin | Administrator | Any | | err | Error | Go (idiomatic), acceptable elsewhere | | ctx | Context | Go (idiomatic), acceptable elsewhere | | req | Request | Handler functions, middleware | | res / resp | Response | Handler functions, middleware | | fn | Function | Callbacks, higher-order functions | | args | Arguments | Any | | params | Parameters | Any | | env | Environment | Configuration, deployment | | src | Source | Build systems, file operations | | dst | Destination | File operations, network | | tmp | Temporary | Only for genuinely temporary values with a lifespan of a few lines | | max | Maximum | Any | | min | Minimum | Any | | len | Length | Any | | num | Number (count of) | Prefixing a noun: numRetries, num_users | | prev | Previous | Iteration, state management | | next | Next | Iteration, state management | | init | Initialize | Startup, constructors | | msg | Message | Messaging systems, logs, chat | | doc | Document | Document management, databases | | img | Image | Media handling, UI | | btn | Button | UI contexts only -- never in backend code | | info | Information | Only as part of a compound: userInfo, errorInfo -- never standalone |

info as a standalone name is banned. See the naming-precision skill. info is only acceptable as a suffix in a compound where the first word provides the specificity: errorInfo, connectionInfo.

The New Hire Test

This is the definitive test for any abbreviation not on the universally understood list.

If a competent developer joining your team today would need to ask "what does this mean?" when reading the code, the abbreviation is unacceptable.

| Abbreviation | Passes? | Why | |-------------|---------|-----| | url | Yes | Every developer knows this | | config | Yes | Universal in software | | btn | Yes (UI) / No (backend) | UI developers know it; backend developers may not | | txn | Borderline | Common in financial codebases, obscure elsewhere. Document it. | | svc | No | Write service | | mgr | No | Write manager (then rename to something precise -- see naming-precision) | | impl | No | Write implementation or, better, name what it implements | | repo | Borderline | Common in DDD codebases. Document it or write repository. | | util | No | Write nothing -- split the utility into specific modules | | acct | No | Write account | | addr | No | Write address | | amt | No | Write amount | | attr | No | Write attribute | | calc | No | Write calculate or calculation | | cb | No | Write callback | | cmd | Borderline | Common in CLI contexts. Write command elsewhere. | | coll | No | Write collection | | desc | No | Write description | | dest | No | Write destination -- or use the approved dst | | dict | Borderline | Python: dict is the type name, fine. Elsewhere: write dictionary or map. | | fmt | Go only | Go's fmt package makes this idiomatic in Go. Write format elsewhere. | | idx | Borderline | Write index. i is fine for loop counters. | | lbl | No | Write label | | lib | Borderline | Common in build systems. Write library in application code. | | obj | No | Name the actual thing. See naming-precision. | | pkg | Go only | Go convention. Write package elsewhere. | | ptr | Go/C only | Idiomatic in systems languages. Write pointer in high-level code. | | ref | No | Write reference | | str | Borderline | Python: str is the type name. Elsewhere: write string. | | tbl | No | Write table | | val | No | Write value -- then rename to something specific. See naming-precision. |

The Consistency Rule

This rule supersedes all others. If you use an abbreviation once, you use it everywhere. If you spell it out once, you spell it out everywhere.

# UNACCEPTABLE: message in one place, msg in another
def send_message(message: str) -> None:
    log.info(f"Sending msg: {message}")       # msg vs message
    queue.publish(msg=message)                 # msg parameter
    track_event("message_sent")               # message in event name

# CORRECT: pick one form and use it everywhere
def send_message(message: str) -> None:
    log.info(f"Sending message: {message}")
    queue.publish(message=message)
    track_event("message_sent")

// UNACCEPTABLE: button in component names, btn in props and handlers
function SubmitButton({ btnText, onBtnClick }: SubmitButtonProps) {
  return <button onClick={onBtnClick}>{btnText}</button>;
}

// CORRECT: one form throughout
function SubmitButton({ buttonText, onButtonClick }: SubmitButtonProps) {
  return <button onClick={onButtonClick}>{buttonText}</button>;
}

// UNACCEPTABLE: request in one function, req in another
func HandleRequest(request *http.Request) { ... }
func validateReq(req *http.Request) error { ... }
func logRequest(request *http.Request) { ... }

// CORRECT: pick one -- in Go handler code, req is idiomatic
func HandleRequest(req *http.Request) { ... }
func validateRequest(req *http.Request) error { ... }
func logRequest(req *http.Request) { ... }

Cross-file consistency is mandatory. If user_service.py uses message and notification_service.py uses msg, the codebase is inconsistent. Grep the codebase. Pick one. Change all occurrences.

The Project-Level Abbreviation Registry

For any abbreviation that is not universally understood but is widely used in your domain, maintain an explicit registry. This is a file in your repository -- not a wiki, not a Confluence page, not tribal knowledge.

# Abbreviation Registry

These abbreviations are approved for use throughout this codebase.
Using the full form is also acceptable. Mixing forms is not.

| Abbreviation | Full Form       | Context                        |
|-------------|-----------------|--------------------------------|
| `txn`       | transaction     | Payment processing, ledger     |
| `repo`      | repository      | Data access layer              |
| `sku`       | stock keeping unit | Inventory, catalog           |
| `qty`       | quantity        | Orders, inventory              |
| `amt`       | amount          | Financial calculations         |
| `org`       | organization    | Multi-tenancy                  |

Rules for the registry:

• It lives in the repository root (e.g., ABBREVIATIONS.md or a section in CONTRIBUTING.md)
• Every entry includes the context where it is used
• Adding a new abbreviation requires team agreement
• The registry is referenced in code review guidelines
• If an abbreviation is not in the registry and not universally understood, it is rejected in review

Acronym Casing Rules

Multi-letter acronyms follow language-specific casing rules. These are covered in detail in the casing-law skill, but the abbreviation-relevant summary is:

| Language | Rule | Example | |----------|------|---------| | Python | Treat as a word in PascalCase | HttpClient, JsonParser, UrlValidator | | TypeScript | Treat as a word in PascalCase/camelCase | HttpClient, jsonParser, urlValidator | | Go | Keep well-known acronyms uppercase | HTTPClient, JSONParser, URLValidator |

Two-letter acronyms are a special case:

• Python / TypeScript: treat as a word: Id, Ip, Io in PascalCase
• Go: keep uppercase: ID, IP, IO

Refer to the casing-law skill for the complete acronym list and handling rules.

Good/Bad Examples

Python

# BAD: Inconsistent abbreviations, unapproved short forms
def calc_ttl_amt(txn_lst, disc_pct):
    ttl = 0
    for txn in txn_lst:
        ttl += txn.amt - (txn.amt * disc_pct / 100)
    return ttl

usr_acct = get_usr_acct(acct_id)
btn_clr = get_btn_clr(theme)
addr_str = fmt_addr(usr_acct.addr)

# GOOD: Full words, clear meaning
def calculate_total_amount(
    transactions: list[Transaction],
    discount_percent: float,
) -> float:
    total = 0.0
    for transaction in transactions:
        total += transaction.amount - (transaction.amount * discount_percent / 100)
    return total

user_account = get_user_account(account_id)
button_color = get_button_color(theme)
formatted_address = format_address(user_account.address)

TypeScript

// BAD: Abbreviated everything, impossible to read without a decoder ring
interface UsrAcct {
  acctId: string;
  dispNm: string;
  regDt: Date;
  lstLoginTs: number;
  emailAddr: string;
  numOrds: number;
}

function updUsrAcctInfo(acctId: string, updData: Partial<UsrAcct>): void { ... }
function getAcctOrds(acctId: string, pgNum: number, pgSz: number): OrdLst { ... }

// GOOD: Full words, instantly readable
interface UserAccount {
  accountId: string;
  displayName: string;
  registrationDate: Date;
  lastLoginTimestamp: number;
  emailAddress: string;
  orderCount: number;
}

function updateUserAccountInfo(accountId: string, updates: Partial<UserAccount>): void { ... }
function getAccountOrders(accountId: string, pageNumber: number, pageSize: number): OrderList { ... }

Go

// BAD: Over-abbreviated, unclear
func ProcMsg(ctx context.Context, msg *Msg) (*Resp, error) {
    v := validateMsg(msg)
    if v != nil {
        return nil, v
    }
    r, err := svc.SendMsg(ctx, msg)
    if err != nil {
        return nil, fmt.Errorf("snd msg: %w", err)
    }
    return r, nil
}

// GOOD: Approved abbreviations only (ctx, msg, err), rest spelled out
func ProcessMessage(ctx context.Context, message *Message) (*MessageResponse, error) {
    validationErr := validateMessage(message)
    if validationErr != nil {
        return nil, validationErr
    }
    response, err := messageService.SendMessage(ctx, message)
    if err != nil {
        return nil, fmt.Errorf("send message: %w", err)
    }
    return response, nil
}

Examples

Working implementations in examples/:

• examples/abbreviation-rules.md -- Multi-language examples showing consistent vs inconsistent abbreviation usage in Python, TypeScript, and Go, with a sample abbreviation registry

Review Checklist

When reviewing code for abbreviation policy compliance:

• [ ] No abbreviations used that are not on the universally understood list or in the project's abbreviation registry
• [ ] Every identifier passes the new hire test: a developer joining today would not need to ask what it means
• [ ] Consistency is absolute: if message is used anywhere, msg is not used in any other file (or vice versa)
• [ ] No mixed forms within the same file, module, or package
• [ ] Multi-letter acronyms follow language-specific casing rules (see casing-law skill)
• [ ] info is never used as a standalone name -- only as part of a compound (errorInfo, connectionInfo)
• [ ] btn is only used in UI-layer code, never in backend or business logic
• [ ] tmp is only used for genuinely temporary values with a lifespan of a few lines
• [ ] Domain-specific abbreviations (txn, sku, qty) are documented in the project's abbreviation registry
• [ ] The abbreviation registry exists if the project uses any non-universal abbreviations
• [ ] No invented abbreviations (acct, addr, calc, desc, lbl, tbl, val) unless explicitly approved and registered
• [ ] Error messages and log strings use full words, not abbreviations