Flag the AI-typical multi-line `//` narration pattern. A `multi-line-comment` is ≥2 consecutive `//` comment lines that are NOT a banner. CLAUDE.md caps in-body `//` comments at one line, so a real prose run is flagged for human collapse or removal. Banner shapes are intentional a
(
lines: list[str], path: Path, fence_mask: list[bool]
)
| 964 | |
| 965 | |
| 966 | def find_comment_style_violations( |
| 967 | lines: list[str], path: Path, fence_mask: list[bool] |
| 968 | ) -> list[Violation]: |
| 969 | """Flag the AI-typical multi-line `//` narration pattern. |
| 970 | |
| 971 | A `multi-line-comment` is ≥2 consecutive `//` comment lines that are |
| 972 | NOT a banner. CLAUDE.md caps in-body `//` comments at one line, so a |
| 973 | real prose run is flagged for human collapse or removal. |
| 974 | |
| 975 | Banner shapes are intentional and skipped: |
| 976 | - `//---` / `//===` decorator rules (with or without a label), |
| 977 | - QML `//` / `// label` / `//` sandwich. |
| 978 | |
| 979 | EDGE CASE FOR LLMs FIXING THESE FLAGS — QML SANDWICH PRESERVATION |
| 980 | ---------------------------------------------------------------- |
| 981 | QML files use a 3-line sandwich convention to label the type/section |
| 982 | that follows: |
| 983 | |
| 984 | // |
| 985 | // Plot area |
| 986 | // |
| 987 | Item { ... } |
| 988 | |
| 989 | This shape is INTENTIONAL and the linter skips it (see `_is_banner_run` |
| 990 | sandwich rule). When you collapse a flagged 5+ line QML prose block |
| 991 | (multi-line text wrapped between `//` decorators), DO NOT drop the |
| 992 | decorators — keep the sandwich, just shorten the inner label to a |
| 993 | single line. Wrong fix: replace the whole block with `// Plot area` |
| 994 | above the `Item { }`. Right fix: |
| 995 | |
| 996 | // |
| 997 | // Plot area |
| 998 | // |
| 999 | Item { ... } |
| 1000 | |
| 1001 | For C++/.cpp/.h/.mm files, the convention is the opposite — a one-line |
| 1002 | `// Section header` directly above the block, no decorators: |
| 1003 | |
| 1004 | // Reset the forward-fill cache for the new file |
| 1005 | m_lastFinalValues.clear(); |
| 1006 | |
| 1007 | Banners with `//---` or `//===` decorators are also intentional in C++ |
| 1008 | and separate concern groups (see CLAUDE.md "98-dash banners separate |
| 1009 | concern groups"). Don't touch those. |
| 1010 | |
| 1011 | HEADER FILES (.h) |
| 1012 | ----------------- |
| 1013 | CLAUDE.md forbids `//` comments before member-variable / signal / |
| 1014 | function declarations in headers. When you encounter a flagged |
| 1015 | multi-line `//` block above a member variable in a header, DELETE |
| 1016 | the whole block — don't shorten it. Names and types are the |
| 1017 | documentation. The only `//` allowed in headers is the SPDX banner |
| 1018 | at the top; the only block-doc allowed is a `/** @brief */` directly |
| 1019 | above a TYPE-LEVEL definition (class, struct, enum, top-level |
| 1020 | typedef/using). If the flagged block is above an enum or struct, you |
| 1021 | can convert it to a one-line `/** @brief ... */`. |
| 1022 | |
| 1023 | Tooling pragmas (`// clang-format off/on`, `// NOLINT`, |
no test coverage detected