ai: add commit style and code comment guidelines#29568
ai: add commit style and code comment guidelines#29568pgellert wants to merge 2 commits intoredpanda-data:devfrom
Conversation
These guidelines have helped me make Claude write better commit messages for me.
This has helped me guide claude to a code commenting style that is less verbose, less prone to becoming stale and more in-line with the style we tend to use in this repo.
There was a problem hiding this comment.
Pull request overview
Adds AI-focused guidance to improve consistency of generated commit messages and reduce unhelpful/stale code comments.
Changes:
- Introduces a “Code comments” section with guidance on when comments are (and aren’t) useful.
- Replaces the brief commit message bullets with a structured format + rules, including when to add commit bodies.
- Adds a suggested
git logcommand to match existing commit style per area.
| - The "what" isn't obvious (summarize distinct changes, new helpers) | ||
| - There's a behavior change or key design decision worth noting | ||
| - Integration tests: briefly note what behaviors are covered | ||
| - Keep bodies concise (1-2 lines typical) |
There was a problem hiding this comment.
I think for some commits I appreciate a full explainer in the commit message. I don't mind if it duplicates a code comment on a class of how it works either, because the commit message is for the reviewer but comments for the code reader
| ``` | ||
|
|
||
| **Rules:** | ||
| - Title: ≤50 chars, imperative mood, lowercase after colon, no period |
There was a problem hiding this comment.
IIRC the limit for title length is 72. See code style, it was also discussed on Slack
There was a problem hiding this comment.
Yeah I looked into this recently and it was my conclusion to.
| ``` | ||
|
|
||
| **Rules:** | ||
| - Title: ≤50 chars, imperative mood, lowercase after colon, no period |
There was a problem hiding this comment.
Seems like we're already referencing CONTRIBUTING.md in this CLAUDE.md. I wonder how well Claude is able to get/adhere to that, and if we should just rely on that as the source of truth for formatting rules and not duplicate it here.
There was a problem hiding this comment.
It will read other files on demand if you put them in here and it thinks they are relevant.
| - **Avoid comments that restate the code** - they become stale | ||
| - **Prefer alternatives:** | ||
| - Better variable/function names | ||
| - Log lines (serve as documentation and debugging) |
There was a problem hiding this comment.
vasserts as well? claude will exhaustively check optionals when sometimes a vassert and operator* would be more appropriate
6 participants
These guidelines have helped me make Claude write better commit messages for me. As well as guiding claude to a code commenting style that is less verbose, less prone to becoming stale and more in line with the style we tend to use in this repo.
These are hopefully generic enough to be useful for all of us, and not too personal/opinionated, but I am curious about others' feedback and am more than happy to adjust.
Backports Required
Release Notes