From bcc74b266455cfb5ebb46af7207d9ef71035fbc0 Mon Sep 17 00:00:00 2001
From: Mathias Fredriksson <mafredri@gmail.com>
Date: Wed, 26 Nov 2025 18:46:37 +0200
Subject: [PATCH] docs: improve code comment guidelines for AI agents (#20952)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR enhances the CLAUDE.md document with comprehensive guidelines
for writing better code comments, specifically targeted at AI agents and
LLM-generated code.

## Changes

- **Proper sentence structure**: Comments should end with punctuation
- **Explain why, not what**: Focus on rationale rather than describing
code
- **Line length and wrapping**: 80-character width with natural wrapping

## Example

The guidelines include before/after examples showing the difference
between well-formatted, meaningful comments and poorly written ones.

## Impact

These standards will help ensure AI-generated code includes
professional, 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 🏂
---
 CLAUDE.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 372835818e..e088e57021 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -140,6 +140,39 @@ seems like it should use `time.Sleep`, read through https://github.com/coder/qua
 - Follow [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)
 - Commit format: `type(scope): message`
 
+### Writing Comments
+
+Code comments should be clear, well-formatted, and add meaningful context.
+
+**Proper sentence structure**: Comments are sentences and should end with
+periods or other appropriate punctuation. This improves readability and
+maintains professional code standards.
+
+**Explain why, not what**: Good comments explain the reasoning behind code
+rather than describing what the code does. The code itself should be
+self-documenting through clear naming and structure. Focus your comments on
+non-obvious decisions, edge cases, or business logic that isn't immediately
+apparent from reading the implementation.
+
+**Line length and wrapping**: Keep comment lines to 80 characters wide
+(including the comment prefix like `//` or `#`). When a comment spans multiple
+lines, wrap it naturally at word boundaries rather than writing one sentence
+per line. This creates more readable, paragraph-like blocks of documentation.
+
+```go
+// Good: Explains the rationale with proper sentence structure.
+// We need a custom timeout here because workspace builds can take several
+// minutes on slow networks, and the default 30s timeout causes false
+// failures during initial template imports.
+ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+
+// Bad: Describes what the code does without punctuation or wrapping
+// Set a custom timeout
+// Workspace builds can take a long time
+// Default timeout is too short
+ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+```
+
 ## Detailed Development Guides
 
 @.claude/docs/ARCHITECTURE.md