Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitbcc74b2

Browse files
authored
docs: improve code comment guidelines for AI agents (#20952)
This PR enhances the CLAUDE.md document with comprehensive guidelinesfor writing better code comments, specifically targeted at AI agents andLLM-generated code.## Changes- **Proper sentence structure**: Comments should end with punctuation- **Explain why, not what**: Focus on rationale rather than describingcode- **Line length and wrapping**: 80-character width with natural wrapping## ExampleThe guidelines include before/after examples showing the differencebetween well-formatted, meaningful comments and poorly written ones.## ImpactThese standards will help ensure AI-generated code includesprofessional, maintainable comments that align with project conventions.---🤖 This change was written by Claude Sonnet 4.5 Thinking using[mux](https://github.com/coder/mux) and reviewed by a human 🏂
1 parent363ed5f commitbcc74b2

File tree

1 file changed

+33
-0
lines changed

1 file changed

+33
-0
lines changed

‎CLAUDE.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,39 @@ seems like it should use `time.Sleep`, read through https://github.com/coder/qua
140140
- Follow[Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)
141141
- Commit format:`type(scope): message`
142142

143+
###Writing Comments
144+
145+
Code comments should be clear, well-formatted, and add meaningful context.
146+
147+
**Proper sentence structure**: Comments are sentences and should end with
148+
periods or other appropriate punctuation. This improves readability and
149+
maintains professional code standards.
150+
151+
**Explain why, not what**: Good comments explain the reasoning behind code
152+
rather than describing what the code does. The code itself should be
153+
self-documenting through clear naming and structure. Focus your comments on
154+
non-obvious decisions, edge cases, or business logic that isn't immediately
155+
apparent from reading the implementation.
156+
157+
**Line length and wrapping**: Keep comment lines to 80 characters wide
158+
(including the comment prefix like`//` or`#`). When a comment spans multiple
159+
lines, wrap it naturally at word boundaries rather than writing one sentence
160+
per line. This creates more readable, paragraph-like blocks of documentation.
161+
162+
```go
163+
// Good: Explains the rationale with proper sentence structure.
164+
// We need a custom timeout here because workspace builds can take several
165+
// minutes on slow networks, and the default 30s timeout causes false
166+
// failures during initial template imports.
167+
ctx,cancel:= context.WithTimeout(ctx,5*time.Minute)
168+
169+
// Bad: Describes what the code does without punctuation or wrapping
170+
// Set a custom timeout
171+
// Workspace builds can take a long time
172+
// Default timeout is too short
173+
ctx,cancel:= context.WithTimeout(ctx,5*time.Minute)
174+
```
175+
143176
##Detailed Development Guides
144177

145178
@.claude/docs/ARCHITECTURE.md

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp