From 11b260142daad1a6b8161ebe1859f1fb670ecb52 Mon Sep 17 00:00:00 2001 From: davidlion <6627627+davidlion@users.noreply.github.com> Date: Thu, 25 Jun 2026 23:50:11 -0400 Subject: [PATCH 1/4] feat(dev-docs): Require the measurement unit in names if it is not in the static type. --- docs/dev-docs/dev-guide/contrib-guides-general.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/dev-docs/dev-guide/contrib-guides-general.md b/docs/dev-docs/dev-guide/contrib-guides-general.md index 42f70a8..38eb3b6 100644 --- a/docs/dev-docs/dev-guide/contrib-guides-general.md +++ b/docs/dev-docs/dev-guide/contrib-guides-general.md @@ -2,6 +2,21 @@ Follow the guidelines below when writing and updating any source files. +## Naming + +### Units + +When handling data with units the unit must always be explicitly stated. +If the unit is not statically available in the type information then it must be added to the name, +preferably as a suffix. + +For example, in C++ when storing a measure of kilobytes inside an integer type name the variable +with a `_kb` suffix (e.g. `encoded_size_kb`). Similarly, when measuring milliseconds in an integer +add an `_ms` suffix (e.g. `parsing_time_ms`). + +An example when it is not necessary to add the unit to the name is when using `std::chrono` in C++ +as the typing (and API) explicitly handles the type. + ## Code organization (declaration-order)= From d9afd19322a1c4b44f0561e2fdbe3b09e6574062 Mon Sep 17 00:00:00 2001 From: davidlion <6627627+davidlion@users.noreply.github.com> Date: Thu, 25 Jun 2026 23:52:26 -0400 Subject: [PATCH 2/4] tweak --- docs/dev-docs/dev-guide/contrib-guides-general.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev-docs/dev-guide/contrib-guides-general.md b/docs/dev-docs/dev-guide/contrib-guides-general.md index 38eb3b6..2bc7a13 100644 --- a/docs/dev-docs/dev-guide/contrib-guides-general.md +++ b/docs/dev-docs/dev-guide/contrib-guides-general.md @@ -4,9 +4,9 @@ Follow the guidelines below when writing and updating any source files. ## Naming -### Units +### Measurement units -When handling data with units the unit must always be explicitly stated. +When handling data with measurement units, the unit must always be explicitly stated. If the unit is not statically available in the type information then it must be added to the name, preferably as a suffix. From 62e3da32db5d5637d7d1b87a3ea2b98be7122f64 Mon Sep 17 00:00:00 2001 From: davidlion <6627627+davidlion@users.noreply.github.com> Date: Fri, 26 Jun 2026 08:26:07 -0400 Subject: [PATCH 3/4] add commas --- docs/dev-docs/dev-guide/contrib-guides-general.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev-docs/dev-guide/contrib-guides-general.md b/docs/dev-docs/dev-guide/contrib-guides-general.md index 2bc7a13..31d19d7 100644 --- a/docs/dev-docs/dev-guide/contrib-guides-general.md +++ b/docs/dev-docs/dev-guide/contrib-guides-general.md @@ -7,10 +7,10 @@ Follow the guidelines below when writing and updating any source files. ### Measurement units When handling data with measurement units, the unit must always be explicitly stated. -If the unit is not statically available in the type information then it must be added to the name, +If the unit is not statically available in the type information, then it must be added to the name, preferably as a suffix. -For example, in C++ when storing a measure of kilobytes inside an integer type name the variable +For example, in C++ when storing a measure of kilobytes inside an integer type, name the variable with a `_kb` suffix (e.g. `encoded_size_kb`). Similarly, when measuring milliseconds in an integer add an `_ms` suffix (e.g. `parsing_time_ms`). From 84584ebf801ad7bf8d6d299b27045d9c27617914 Mon Sep 17 00:00:00 2001 From: davidlion <6627627+davidlion@users.noreply.github.com> Date: Thu, 2 Jul 2026 09:34:51 -0400 Subject: [PATCH 4/4] Fix explanations per-review. --- docs/dev-docs/dev-guide/contrib-guides-general.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/dev-docs/dev-guide/contrib-guides-general.md b/docs/dev-docs/dev-guide/contrib-guides-general.md index 31d19d7..3b4256d 100644 --- a/docs/dev-docs/dev-guide/contrib-guides-general.md +++ b/docs/dev-docs/dev-guide/contrib-guides-general.md @@ -10,16 +10,20 @@ When handling data with measurement units, the unit must always be explicitly st If the unit is not statically available in the type information, then it must be added to the name, preferably as a suffix. -For example, in C++ when storing a measure of kilobytes inside an integer type, name the variable -with a `_kb` suffix (e.g. `encoded_size_kb`). Similarly, when measuring milliseconds in an integer -add an `_ms` suffix (e.g. `parsing_time_ms`). +For example, in C++ when storing a measure of kibibytes inside an integer type, name the variable +with a `_kib` suffix (e.g. `encoded_size_kib`). -An example when it is not necessary to add the unit to the name is when using `std::chrono` in C++ -as the typing (and API) explicitly handles the type. +It is not a requirement to use abbreviations, as the goal is clarity. For example, when measuring +milliseconds adding `_ms` is actually ambiguous as to whether it's milli or mega, so we use +`_millisecs` (e.g. `parsing_time_millisecs`). + +Using `std::chrono` in C++ is an example of when the type (and API) explicitly handles the unit and +it is unnecessary to add a suffix. ## Code organization (declaration-order)= + ### Declaration order Organize declarations in order of: