Skip to content

doc(reference): add a rule on comment brevity - #62

Merged
kniz merged 3 commits into
mainfrom
doc/comment-brevity
Aug 29, 2026
Merged

kniz merged 3 commits into
mainfrom
doc/comment-brevity

Conversation

@kniz

@kniz kniz commented Aug 29, 2026 •

Copy link
Copy Markdown
Member

What

Two things in the documentation standards of ad-convention-rules:

  1. A new rule on comment brevity — how much to write, once you have decided to comment.
  2. The existing doxygen examples, rewritten in English — they were almost all Korean.

Why the new rule

The section already covers comment form (doxygen style, which tags, where TODO notes go) and whether to comment at all — there is a rule against commenting self-evident code. What it never covered is how much to write.

That gap keeps showing up in review. Most recently on launcher#12, where a nine-line CMake comment drew a one-line rejection: write only the essentials, stop rambling. Without a written rule there is nothing to point at, and the same note gets repeated by hand each time.

It sits directly after the existing rule against commenting self-evident code, because the two are the same decision one step apart — first whether to comment, then how much.

The rule itself: comments carry the why; the code already states the what. Three checks:

  • Don't stretch a one-line explanation across several lines
  • Don't add @details when @brief already covers it
  • Stop background explanation at the point that justifies the decision

Both examples are real, taken from the review that prompted this — a @details block that says the same thing three times, and a three-line file header that survives as one line.

Why the translation

An example shows what a comment should look like, so the comment inside it has to be the real article — and this codebase writes those in English. Nearly every doxygen sample in the document was Korean, which taught the opposite of what the project does.

Translated: @brief, @details, @param, @return bodies and the @file descriptions. The good/bad example labels stay Korean, since they speak to the reader rather than forming part of the sample. The prose stays Korean throughout, like the rest of doc/ref/ko/.

One detail worth checking on review: the column-limit block demonstrates the 100 and 120 column caps, so the translated lines were measured to keep landing on the same side of each cap — 56, 105 and 135 columns respectively.

Scope

Only doc/ref/ko/ is touched. doc/ref/en/ currently holds just MAINPAGE.md, so there is no English counterpart to update.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FxEguTsAzmbb3v6MhmxnAz

kniz-bot and others added 3 commits August 29, 2026 17:23
The documentation standards covered comment form -- doxygen style, which
tags, where notes go -- and whether to comment at all, but never how much
to write once you decide to. Review feedback keeps landing on that gap.

Add it next to the rule on omitting obvious comments, since the two are
the same decision one step apart: first whether, then how much.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxEguTsAzmbb3v6MhmxnAz
Prose stays Korean like the rest of the document, but the code inside the
examples is English -- that is what the examples are teaching people to
write.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxEguTsAzmbb3v6MhmxnAz
The examples show what a comment should look like, so the comment inside
them has to be the real thing -- and the codebase writes those in English.
Nearly every doxygen sample here was Korean instead.

Translate the tag bodies: @brief, @details, @PARAM, @return and the file
descriptions. Labels like `// 나쁜 예` stay Korean since they address the
reader rather than being part of the sample.

The column limit examples keep their lengths on the right side of the
100 and 120 column marks, which is the whole point of that block.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxEguTsAzmbb3v6MhmxnAz
@kniz
kniz merged commit 8c0d30b into main Aug 29, 2026
6 checks passed
@kniz
kniz deleted the doc/comment-brevity branch August 29, 2026 08:32
@codecov

codecov Bot commented Aug 29, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants