From cee310521fff2bd42cd45723384ad83066a0e10a Mon Sep 17 00:00:00 2001 From: Yung-Yu Chen Date: Mon, 15 Jun 2026 23:07:22 +0800 Subject: [PATCH 1/2] Add comment and commit-log style guidelines --- STYLE.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 113 insertions(+), 7 deletions(-) diff --git a/STYLE.md b/STYLE.md index 5c4513aa..8d182c5b 100644 --- a/STYLE.md +++ b/STYLE.md @@ -385,17 +385,84 @@ level. Do not duplicate the same test in both layers without a reason. A test should encode why a behavior matters, not merely what it does. A test that cannot fail when the logic it covers changes is not pulling its weight. -## Integer Type +## Comments + +A comment carries what the code cannot: the intent, the constraints, and the +reasoning that the syntax leaves implicit. Code says what happens; a good +comment says why it happens and what a reader must know but cannot see. This +follows the same economy as the rest of the guide -- a comment that merely +restates the code is noise, and noise is removed. + +We write comments clearly and concisely. Comments must not interfere +readability. + +Write comments at two levels, and keep them separate: + +- Interface comments sit before a function, class, or member and describe how + to use it: what it does, the meaning and units of each argument and return + value, who owns any allocated memory, which values are sentinels (a null + pointer, `-1`, an empty array), and the invariants the caller must uphold. +- Implementation comments sit inside the body and explain what is not obvious + from reading it: the steps of a non-trivial algorithm, why one approach was + chosen over a viable alternative, or a single tricky line. Do not repeat the + interface comment here. + +Because this codebase solves numerical problems, the non-obvious facts are +often physical or structural. State them: + +- Units, coordinate conventions, and index bases that the types do not encode. +- The expected shape, layout, or contiguity of an array or buffer. +- Invariants tying several variables together (e.g. a count that must equal a + buffer length). +- For any formula, cite the literature, equation, or document it comes from so + the next reader can verify it. + +Further conventions: + +- Prefer a clear name over a comment. If a comment exists only to explain an + obscure name, rename instead. A comment cannot rescue an unclear design. +- Keep the rationale in the comment, next to the code -- not only in a commit + message or pull request, which are hard to find later. When you change the + code, change the comment in the same edit. +- Write comments as full sentences with capitalization and a closing period. + The verb mood differs by language -- the C++ and Python sections below fix + it -- so a function summary reads as prose, not a fragment. Use ASCII only. +- A comment describes the code, never the task or conversation that produced + it. Do not write "as requested" or reference a review thread in a source + comment. + +### C++ Comment + +The general comment rules above apply to C++. Write the summary of a function +or class in the descriptive mood ("Opens the file.", "Returns the cell +count."). Comment blocks follow [the doxygen style +guidelines](https://www.doxygen.nl/manual/docblocks.html) if convenient. -Use fixed-width integers (`int32_t`, `uint8_t`, etc.) Do not use the basic -integer types (`int`, `long`, etc.) unless there is not another choice. +If possible, provide references to literature or documents in comments. -## C++ Comment +### Python Comment + +The general comment rules above apply to Python. The interface comment is the +docstring, not a `#` comment: give every public module, class, function, and +method a `"""triple-quoted"""` docstring, per [PEP +257](https://peps.python.org/pep-0257/). Reserve `#` comments for +implementation notes inside a body. + +- If a function or class is obvious, do not add a docstring. +- Begin a docstring with a one-line summary that ends with a period. Unlike a + C++ comment, the summary is imperative -- it prescribes what a call does as a + command ("Run the solver.", "Return the cell count."), matching PEP 257 and + the docstrings already in the tree. +- For a multi-line docstring, follow the summary with a blank line, then the + detail, and keep the closing `"""` on its own line. +- When documenting arguments and return values, use the reStructuredText field + syntax already used in the codebase (`:param name:`, `:return:`, `:rtype:`) + rather than introducing a second docstring dialect. -Comment blocks follow [the doxygen style -guidelines](https://www.doxygen.nl/manual/docblocks.html) if convenient. +## Integer Type -If possible, provide references to literature or documents in comments. +Use fixed-width integers (`int32_t`, `uint8_t`, etc.) Do not use the basic +integer types (`int`, `long`, etc.) unless there is not another choice. ## C++ Include File @@ -707,6 +774,45 @@ if (condition) return; ``` +## Commit Log + +A commit message records why a change happened, which the diff cannot show. +Write it for the person who runs `git log` or `git blame` a year from now. We +do not use semantic (conventional) commit prefixes such as `feat:` or `fix:`. + +We write comments clearly and concisely, like carefully-thinking professionals +do. + +Structure a message as a subject line, a blank line, and an optional body: + +- Write the subject in the imperative mood, completing the sentence "If + applied, this commit will ..." -- "Add the oblique-shock Euler driver", not + "Added ..." or "Adds ...". This matches git's own messages ("Merge ...", + "Revert ..."). +- Capitalize the subject and do not end it with a period. +- Aim for a subject of 50 characters; treat 72 as the hard limit. +- Separate the subject from the body with one blank line; many git tools rely + on this split. +- Wrap the body at 72 characters. Git does not wrap it for you. + +Use the body to explain what changed and why, not how -- the diff already +shows how. Make it self-contained: a reader should judge the change without +opening the patch. Describe the behavior before the change in the present +tense ("The solver drains to vacuum at a slip wall"), then say why the new +behavior is better. If you considered and rejected an alternative, name it. Do +not point at a chat log or mailing-list thread for the reasoning; summarize it +in the message. + +A one-line subject is enough when the change is trivial and needs no context +(e.g. "Fix typo in the buffer header"). Add a body whenever the reason is not +obvious from the subject. + +Do not reference issues or PRs directly in the commit log, unless you have to. +In the rare occasions to reference issues, follow the rule in `CLAUDE.md`: end +the body with "Related to #xxx" or "For issue #xxx". Never use closing keywords +(`close`, `fixes`, `resolves`, ...); commit text must not drive issue +management. + ## Copyright Notice modmesh uses the [BSD license](http://opensource.org/licenses/BSD-3-Clause). From 59a5db3373a2102d3038d38ae3400c7fb17e97c0 Mon Sep 17 00:00:00 2001 From: Yung-Yu Chen Date: Tue, 16 Jun 2026 08:02:04 +0800 Subject: [PATCH 2/2] Tighten the Comments section in STYLE.md --- STYLE.md | 69 ++++++++++++++++++++++++-------------------------------- 1 file changed, 29 insertions(+), 40 deletions(-) diff --git a/STYLE.md b/STYLE.md index 8d182c5b..78500efb 100644 --- a/STYLE.md +++ b/STYLE.md @@ -387,58 +387,47 @@ that cannot fail when the logic it covers changes is not pulling its weight. ## Comments -A comment carries what the code cannot: the intent, the constraints, and the -reasoning that the syntax leaves implicit. Code says what happens; a good -comment says why it happens and what a reader must know but cannot see. This -follows the same economy as the rest of the guide -- a comment that merely -restates the code is noise, and noise is removed. - -We write comments clearly and concisely. Comments must not interfere -readability. - -Write comments at two levels, and keep them separate: +Code says what happens. A comment says why, and what a reader must know but +cannot see. Do not write a comment that merely restates the code (it is only +noise). Write comments clearly and concisely, and keep two levels separate: - Interface comments sit before a function, class, or member and describe how to use it: what it does, the meaning and units of each argument and return value, who owns any allocated memory, which values are sentinels (a null pointer, `-1`, an empty array), and the invariants the caller must uphold. -- Implementation comments sit inside the body and explain what is not obvious - from reading it: the steps of a non-trivial algorithm, why one approach was - chosen over a viable alternative, or a single tricky line. Do not repeat the - interface comment here. +- Implementation comments sit inside the body and explain what reading it does + not reveal: a non-trivial algorithm, why one approach was chosen over a + viable alternative, or a single tricky line. Do not repeat the interface + comment. -Because this codebase solves numerical problems, the non-obvious facts are -often physical or structural. State them: +Because this codebase solves numerical problems, state the physical and +structural facts the types do not encode: -- Units, coordinate conventions, and index bases that the types do not encode. +- Units, coordinate conventions, and index bases. - The expected shape, layout, or contiguity of an array or buffer. - Invariants tying several variables together (e.g. a count that must equal a buffer length). -- For any formula, cite the literature, equation, or document it comes from so - the next reader can verify it. +- For any formula, cite the literature, equation, or document it comes from. Further conventions: -- Prefer a clear name over a comment. If a comment exists only to explain an - obscure name, rename instead. A comment cannot rescue an unclear design. -- Keep the rationale in the comment, next to the code -- not only in a commit - message or pull request, which are hard to find later. When you change the - code, change the comment in the same edit. +- Prefer a clear name over a comment; rename rather than explain an obscure + name. A comment cannot rescue an unclear design. +- Keep the rationale next to the code, not only in a commit message or pull + request. When you change the code, change the comment in the same edit. - Write comments as full sentences with capitalization and a closing period. The verb mood differs by language -- the C++ and Python sections below fix - it -- so a function summary reads as prose, not a fragment. Use ASCII only. + it. Use ASCII only. - A comment describes the code, never the task or conversation that produced - it. Do not write "as requested" or reference a review thread in a source - comment. + it. Do not write "as requested" or reference a review thread. +- If possible, provide references (with URL) to literature or documents in + comments. ### C++ Comment -The general comment rules above apply to C++. Write the summary of a function -or class in the descriptive mood ("Opens the file.", "Returns the cell -count."). Comment blocks follow [the doxygen style -guidelines](https://www.doxygen.nl/manual/docblocks.html) if convenient. - -If possible, provide references to literature or documents in comments. +The general comment rules above apply to C++. Comment blocks follow [the +doxygen style guidelines](https://www.doxygen.nl/manual/docblocks.html) if +convenient. ### Python Comment @@ -449,15 +438,15 @@ method a `"""triple-quoted"""` docstring, per [PEP implementation notes inside a body. - If a function or class is obvious, do not add a docstring. -- Begin a docstring with a one-line summary that ends with a period. Unlike a - C++ comment, the summary is imperative -- it prescribes what a call does as a - command ("Run the solver.", "Return the cell count."), matching PEP 257 and - the docstrings already in the tree. +- Begin a docstring with a one-line summary that ends with a period. It + prescribes what a call does as a command ("Run the solver.", "Return the cell + count."). - For a multi-line docstring, follow the summary with a blank line, then the detail, and keep the closing `"""` on its own line. -- When documenting arguments and return values, use the reStructuredText field - syntax already used in the codebase (`:param name:`, `:return:`, `:rtype:`) - rather than introducing a second docstring dialect. +- When documenting arguments and return values, use the + Sphinx/reStructuredText field syntax already used in the codebase (`:param + name:`, `:return:`, `:rtype:`) rather than introducing a second docstring + dialect. ## Integer Type