From 925c824ddbdc800f9e0413402c95c34ab3b35391 Mon Sep 17 00:00:00 2001 From: Noah Dietz Date: Fri, 27 Dec 2024 11:00:33 -0800 Subject: [PATCH] fix(AIP-140): add abbreviations field name guidance (#1465) --- aip/general/0140.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/aip/general/0140.md b/aip/general/0140.md index 611675903c..0a4154510b 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -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 @@ -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.