From cee310521fff2bd42cd45723384ad83066a0e10a Mon Sep 17 00:00:00 2001 From: Yung-Yu Chen Date: Mon, 15 Jun 2026 23:07:22 +0800 Subject: [PATCH] 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).