Skip to content

Commit

Permalink
fix(AIP-140): add abbreviations field name guidance (#1465)
Browse files Browse the repository at this point in the history
  • Loading branch information
noahdietz authored Dec 27, 2024
1 parent af6d478 commit 925c824
Showing 1 changed file with 14 additions and 0 deletions.
14 changes: 14 additions & 0 deletions aip/general/0140.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,19 @@ preposition must be present to accurately convey the unit. Additionally, "per"
is often appropriate in reporting scenarios (e.g. "nodes per instance" or
"failures per hour").

### Abbreviations

For well known name abbreviations among software developers, such as "config"
and "spec", the abbreviations **should** be used in API definitions instead of
the full spelling. This will make the source code easy to read and write.
Examples:

- `config` (**not** `configuration`)
- `id` (**not** `identifier`)
- `info` (**not** `information`)
- `spec` (**not** `specification`)
- `stats` (**not** `statistics`)

### Adjectives

For uniformity, field names that contain both a noun and an adjective
Expand Down Expand Up @@ -162,6 +175,7 @@ field **should not** have a uniqueness requirement.

## Changelog

- **2024-12-20**: Copy over abbreviations guidance from old design site.
- **2024-08-26**: Codify exception to string and base64 guidance
- **2024-05-18**: Documented the effect of field names on client surfaces.
- **2023-04-25**: Field names **must not** be expressed as verbs.
Expand Down

0 comments on commit 925c824

Please sign in to comment.