Skip to content

feat(dev-docs): Require the measurement unit in names if it is not in the static type. #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
davidlion wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat(dev-docs): Require the measurement unit in names if it is not in the static type. #65

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
11b2601
feat(dev-docs): Require the measurement unit in names if it is not in…
davidlion Jun 26, 2026
d9afd19
tweak
davidlion Jun 26, 2026
62e3da3
add commas
davidlion Jun 26, 2026
84584eb
Fix explanations per-review.
davidlion Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/dev-docs/dev-guide/contrib-guides-general.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,28 @@

Follow the guidelines below when writing and updating any source files.

## Naming

### 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,
preferably as a suffix.
Comment thread
coderabbitai[bot] marked this conversation as resolved.

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`).

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`).
Comment on lines +16 to +18

@coderabbitai coderabbitai Bot Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer a clearer unit suffix in the example.

This example still relies on a fairly terse abbreviation, which weakens the “clarity” rule you just introduced. Consider spelling out the unit in the sample identifier so the guidance is self-explanatory.

Proposed wording 
-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`).
+For example, when measuring milliseconds, use a `_milliseconds` suffix (e.g. `parsing_time_milliseconds`).
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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`).
It is not a requirement to use abbreviations, as the goal is clarity. For example, when measuring
milliseconds, use a `_milliseconds` suffix (e.g. `parsing_time_milliseconds`).
🧰 Tools
🪛 LanguageTool

[style] ~17-~17: Consider shortening this phrase to just “whether”, or rephrase the sentence to avoid “as to”.
Context: ...onds adding _ms is actually ambiguous as to whether it's milli or mega, so we use `_millise...

(WHETHER)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/dev-docs/dev-guide/contrib-guides-general.md` around lines 16 - 18, The
example in the contributor guide still uses a somewhat abbreviated unit suffix,
which conflicts with the new clarity guidance. Update the sample identifier in
the paragraph to use a fully spelled-out unit name so the example itself
demonstrates the rule; adjust the wording around the milliseconds example and
the identifier shown in the guidance to keep the convention consistent and
self-explanatory.

@davidlion davidlion Jul 2, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kirkrodrigues I'm guessing there is a better word for "clarity" here that also address the rabbit's concern (I don't fully agree with it, but I see its point).

@coderabbitai coderabbitai Bot Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@davidlion, since your main concern was ambiguity between "milli" and "mega" rather than clarity in general, you could reframe the goal around unambiguity rather than (or in addition to) clarity. A few options:

  1. "It is not a requirement to use abbreviations, as the goal is to avoid ambiguity."
  2. "It is not a requirement to use abbreviations, as the goal is clarity and unambiguity."
  3. "Abbreviations are not required; prefer whichever form is unambiguous and easy to recognize."

Option 1 directly ties the rule to the actual problem being illustrated (the _ms milli/mega confusion), which should satisfy the original nit without necessarily forcing a fully spelled-out suffix like _milliseconds — you could still keep _millisecs as the example if you feel that's unambiguous enough in your codebase's context. Let me know which direction you'd like and I can help refine the wording further.


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:
Expand Down