From 35213e914ed9075c86262ef0a166faa561af38ae Mon Sep 17 00:00:00 2001 From: Thomas Vegas Date: Fri, 28 Aug 2026 10:00:30 +0200 Subject: [PATCH 1/3] DOCS: Add comment style guidance to CodeStyle.md Codify how in-source comments should read (short, explain why not what, no PR/issue or dev-process narration, documented once) based on existing UCX comment conventions, and point AGENTS.md at it. --- AGENTS.md | 2 +- docs/CodeStyle.md | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2a4b74a3f4c..ccb386f7ff5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,7 @@ Other top-level areas: Follow these project docs instead of duplicating their contents: -- `docs/CodeStyle.md` for C/C++ formatting and naming. +- `docs/CodeStyle.md` for C/C++ formatting, naming, and comment style. - `docs/LoggingStyle.md` for log levels and message style. - `docs/OptimizationStyle.md` for performance-sensitive changes. - `REVIEW.md` for UCX pull-request review checks and comment style. diff --git a/docs/CodeStyle.md b/docs/CodeStyle.md index a7aa9ad1f21..bbfc50dba9a 100644 --- a/docs/CodeStyle.md +++ b/docs/CodeStyle.md @@ -18,6 +18,16 @@ * Use `ucs_assert*` for internal invariants, not user-input validation. +## Comments + * Usually one line; more only for a non-obvious, complex point, or Doxygen + doc for public headers or non-trivial functions. + * Document 'Why' not 'What'; no PR/issue references, no dev-process + narration. + * Document once, in the most relevant area; do not duplicate elsewhere. + * Explain locking, ownership, tradeoffs, or step-by-step processing when + non-obvious. + + ## Naming convention: * Lower case, underscores * Names must begin with ucp_/uct_/ucs_/ucm_ From 191b341429c539331a1697d254b0877736799339 Mon Sep 17 00:00:00 2001 From: Thomas Vegas Date: Fri, 28 Aug 2026 11:48:04 +0300 Subject: [PATCH 2/3] DOCS: Add comment style guidance to CodeStyle.md --- docs/CodeStyle.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CodeStyle.md b/docs/CodeStyle.md index bbfc50dba9a..c1299fd33e3 100644 --- a/docs/CodeStyle.md +++ b/docs/CodeStyle.md @@ -19,11 +19,11 @@ ## Comments - * Usually one line; more only for a non-obvious, complex point, or Doxygen - doc for public headers or non-trivial functions. - * Document 'Why' not 'What'; no PR/issue references, no dev-process + * Usually one line; use more only for a non-obvious or complex point, or + per the `## Doxygen` section below. + * Document `why` not `what`; no PR/issue references, no dev-process narration. - * Document once, in the most relevant area; do not duplicate elsewhere. + * Document once, in the most relevant area. * Explain locking, ownership, tradeoffs, or step-by-step processing when non-obvious. From 8293ba4888f6d0d744e25abd0d63e85259488191 Mon Sep 17 00:00:00 2001 From: Thomas Vegas <125344591+tvegas1@users.noreply.github.com> Date: Mon, 31 Aug 2026 12:06:44 +0200 Subject: [PATCH 3/3] Apply suggestion from @guy-ealey-morag Co-authored-by: Guy Ealey Morag --- docs/CodeStyle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CodeStyle.md b/docs/CodeStyle.md index c1299fd33e3..e96bfa8edda 100644 --- a/docs/CodeStyle.md +++ b/docs/CodeStyle.md @@ -21,7 +21,7 @@ ## Comments * Usually one line; use more only for a non-obvious or complex point, or per the `## Doxygen` section below. - * Document `why` not `what`; no PR/issue references, no dev-process + * Focus on "why" rather than "what"; no PR/issue references, no dev-process narration. * Document once, in the most relevant area. * Explain locking, ownership, tradeoffs, or step-by-step processing when