Abbreviation Policy

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.

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.

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:

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