From fbb07399f87fd853ce30b817fa287ec6088eb331 Mon Sep 17 00:00:00 2001 From: Joel Lamy-Poirier Date: Fri, 1 May 2026 07:16:59 -0400 Subject: [PATCH] Add comment policy to Code Style in CLAUDE.md The PR review checklist already flagged comments that restate obvious code, but the Code Style section had no comment guidance. Coder sessions read Code Style to guide generation and found no constraint, so they defaulted to verbose comments; reviewer sessions then flagged them. Add an explicit Comments entry so both sides apply the same rule. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CLAUDE.md b/CLAUDE.md index 265b017cb..efac8ae7f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -167,6 +167,7 @@ Tests live in `tests/`. The following patterns work well in this codebase. ## Code Style +- **Comments**: Write no comments by default. Only add one when the WHY is non-obvious — a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader. Never restate what the code already says; well-named identifiers do that. - **Imports**: Third-party → `import package.module` (keep fully qualified). First-party → `from fast_llm.module import Thing`. No relative imports. Optional/slow imports inside methods or under `if typing.TYPE_CHECKING:`. - **Naming**: No abbreviations (use `batch_size` not `bs`). Private members get a single `_` prefix; never use `__`. Keep public interfaces lean. - **Types**: Always type-hint public interfaces. Use modern syntax (`X | Y`, `list[T]` not `List[T]`, PEP 695 generics like `class X[T: Bound]:` instead of `typing.TypeVar`).