From 7b631dd49c56101d75776349c6a1ea6f7d67ba49 Mon Sep 17 00:00:00 2001 From: dayfine Date: Wed, 18 Nov 2026 21:02:01 -0800 Subject: [PATCH] code health: drop the header-comment contract Comments only when it's not obvious: a header symbol whose name says what it is needs no comment. AGENTS.md says the same. The advisory for a comment that describes the neighbouring function stays. --- AGENTS.md | 9 ++--- devtools/code_health/README.md | 4 --- devtools/code_health/style.py | 36 -------------------- devtools/code_health/tests/test_cli.py | 2 +- devtools/code_health/tests/test_contracts.py | 16 +++------ 5 files changed, 11 insertions(+), 56 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7483356a8d..65953d0b06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -252,7 +252,8 @@ See [pokemon_sv/PR_WORKFLOW.md](pokemon_sv/PR_WORKFLOW.md). In short: removed, and compare `git diff --stat` with the estimate; cut what has no answer. - **Types, names and comments** (the user's review of fork PR #648; apply on every file of a chain, writing and reviewing): - - **Name a type for what it is**, then drop the comment that only restates the name. + - **Comments only when it's not obvious.** Name a type for what it is, then drop the + comment that only restates the name. #648: "An engine run of one checkpoint" became `CheckpointRunResult`, no comment. - **A name says what kind of value it holds:** index or count, 0- or 1-based. #648: `failed_event` became `failed_event_index`. @@ -370,9 +371,9 @@ so keep it where it clearly pays off. `std::string_view` is the exception (see S Function templates in headers declare their public API before internal helper namespaces; internal helper templates are defined in place. Definitions stay in the same header; this is not permission to forward-declare external types. -- **Header documentation:** comment every namespace-scope symbol, including - types, aliases, constants and internal helpers. A function definition may reuse - its documented declaration in the same header. Code Health checks changed symbols. +- **Header documentation:** comment a header symbol only when its name and signature don't + already say what it is (user, 2026-11-18). No symbol needs a comment; Code Health doesn't + ask for one. - **Unsigned:** counts and indexes are `size_t` / `uint8_t` (Google prefers `int`). Match that, and see TotW #227 below. - **Callbacks:** APIs such as `run_until()` take `std::function<...>&&`. Match the API diff --git a/devtools/code_health/README.md b/devtools/code_health/README.md index 2a9620025f..e95eb4d527 100644 --- a/devtools/code_health/README.md +++ b/devtools/code_health/README.md @@ -260,10 +260,6 @@ and declarations are enforced; untouched legacy declarations are grandfathered. - `template-api-internal`: internal helper templates are defined in place, with no separate forward declaration. A header containing only internal helpers needs no invented public API. -- `header-comment`: document each added/changed namespace-scope header symbol, - including helper declarations, types, aliases, and constants. An immediately - adjacent `//` or block/Doxygen comment counts. A definition can reuse its own - documented declaration. Class members and namespaces themselves are excluded. - `test-case`: new/changed native `*_Tests.cpp` UnitTest classes take one aggregate case. That case has exactly three fields, in order: `name`, `input` and `expectation`. The name labels the case and is not part of what the code under test is given, diff --git a/devtools/code_health/style.py b/devtools/code_health/style.py index f7170b1903..266da1ff33 100644 --- a/devtools/code_health/style.py +++ b/devtools/code_health/style.py @@ -605,41 +605,6 @@ def template_order(path, parsed, changed): return errors -def documented(lines, line): - """Accept adjacent // prose or a closed block comment, including Doxygen.""" - if line < 2: - return False - above = lines[line - 2].strip() - if above.startswith('//'): - return bool(above.lstrip('/').strip()) - if not above.endswith('*/'): - return False - for earlier in reversed(lines[:line - 1]): - if '/*' in earlier: - return True - if not earlier.strip().startswith(('*', '//')): - return False - return False - - -def header_comments(path, lines, parsed, changed): - errors, documented_functions = [], set() - for statement, enclosing in scopes(parsed): - text = statement.text - if not statement.namespace_scope or statement.end == '}': - continue - if not text or re.match(r'(?:inline\s+)?namespace\b|(?:static_assert|extern\s*")', text): - continue - key = function_key(statement, enclosing) - has_comment = documented(lines, statement.line) - if has_comment and key: - documented_functions.add(key) - if statement.line in changed and not has_comment and key not in documented_functions: - errors.append(Finding(path, statement.line, - 'header-comment: document each namespace-scope header symbol')) - return errors - - def structures(parsed): """Local aggregate definitions and their directly declared fields.""" found = {} @@ -876,6 +841,5 @@ def check(path, source, previous_source): errors += native_cases(path, '\n'.join(code), statements_, added) if path.endswith(HEADERS): errors += template_api(path, statements_, added) - errors += header_comments(path, raw_lines, statements_, added) warnings += comment_checks(path, raw_lines, statements_, added) return sorted(errors + more_errors, key=lambda f: f.line), sorted(warnings, key=lambda f: f.line) diff --git a/devtools/code_health/tests/test_cli.py b/devtools/code_health/tests/test_cli.py index 32be713ba5..24e14cd9d3 100644 --- a/devtools/code_health/tests/test_cli.py +++ b/devtools/code_health/tests/test_cli.py @@ -277,7 +277,7 @@ def test_structural_header_findings_reach_cli_and_annotations(self): self.git('add', '.') red = self.cli('--github') self.assertEqual(1, red.returncode) - for rule in ('namespace-close', 'template-api', 'header-comment'): + for rule in ('namespace-close', 'template-api'): self.assertIn(rule, red.stderr) self.assertIn('::error file=Common/policy.h', red.stdout) header.write_text('namespace Policy{\n// Return the value.\n' diff --git a/devtools/code_health/tests/test_contracts.py b/devtools/code_health/tests/test_contracts.py index 712a579fee..eb40d89675 100644 --- a/devtools/code_health/tests/test_contracts.py +++ b/devtools/code_health/tests/test_contracts.py @@ -30,11 +30,9 @@ def test_template_header_declaration_precedes_definition(self): declaration = '// Identity.\ntemplate \nT identity(T value);\n' self.assertFalse(any('template-api' in m for m in self.messages(declaration + body))) - def test_top_level_header_symbols_have_comments(self): - source = 'struct Limits{};\nusing Count = int;\nvoid run();\n' - self.assertEqual(3, sum('header-comment' in m for m in self.messages(source))) - documented = '// Search budget.\nstruct Limits{};\n// Number of tiles.\nusing Count = int;\n// Execute.\nvoid run();\n' - self.assertFalse(any('header-comment' in m for m in self.messages(documented))) + def test_header_symbols_whose_name_says_it_all_need_no_comment(self): + source = 'struct CheckpointRunResult{};\nusing Count = int;\nvoid run();\n' + self.assertEqual([], self.messages(source)) def test_native_cases_separate_input_and_expectation_in_a_table(self): good = '''struct Case{ @@ -123,8 +121,8 @@ def test_namespace_names_anonymous_nested_and_literal_braces(self): def test_unchanged_debt_is_grandfathered(self): old = 'namespace Old{\nstruct Limits{};\n}\n' self.assertEqual([], self.messages(old + '\n// unrelated edit\n', previous=old)) - new = old.replace('struct Limits{};', 'struct NewLimits{};') - self.assertEqual(1, sum('header-comment' in m for m in self.messages(new, previous=old))) + new = old.replace('}\n', '} // namespace Wrong\n') + self.assertEqual(1, sum('namespace-close' in m for m in self.messages(new, previous=old))) def test_all_header_symbol_kinds_and_methods(self): source = '''// This block documents only First. @@ -134,7 +132,6 @@ def test_all_header_symbol_kinds_and_methods(self): constexpr int COUNT = 3; template struct Box{ void method(){}; T value; }; ''' - self.assertEqual(4, sum('header-comment' in m for m in self.messages(source))) self.assertFalse(any('template-api' in m for m in self.messages(source))) def test_block_comments_and_documented_redeclaration(self): @@ -214,9 +211,6 @@ def test_header_namespace_comments_are_not_required_for_class_closes(self): self.assertEqual([], self.messages(source)) self.assertEqual([], self.messages('namespace A::B{\n} // namespace A::B\n')) - def test_empty_comments_do_not_document_a_header_symbol(self): - self.assertTrue(any('header-comment' in m for m in self.messages('//\nvoid run();\n'))) - def test_changed_native_test_class_is_checked(self): old = 'class Test_Value : public UnitTest{\npublic:\n Test_Value(int input, int expected){}\n};\n' new = old.replace('int expected', 'long expected')