writing-comments
Reference guide for code comment formatting rules and examples. The core rules are automatically applied via CLAUDE.md system instructions - this skill provides detailed examples and edge cases for reference.
When & Why to Use This Skill
This Claude skill serves as a comprehensive reference guide for code comment formatting and documentation best practices. It establishes clear, actionable rules for standalone versus inline comments, multi-line syntax, and semantic line breaks to ensure maximum code readability. By emphasizing the 'why' behind logic rather than just the 'what' and providing language-specific guidelines like GoDoc, this skill helps developers maintain professional, clean, and meaningful codebases while eliminating redundant or low-value commentary.
Use Cases
- Standardizing documentation across large-scale software projects to ensure all team members follow the same commenting syntax and logic.
- Assisting in code reviews by providing a clear benchmark for documentation quality, helping teams identify and remove unnecessary or poorly formatted comments.
- Onboarding new engineers to a project's specific coding standards, specifically regarding GoDoc conventions and sentence-based comment structures.
- Optimizing AI-assisted coding workflows by providing the agent with precise rules for generating human-centric, context-aware code explanations that follow professional standards.
| name | writing-comments |
|---|---|
| description | Reference guide for code comment formatting rules and examples. The core rules are automatically applied via CLAUDE.md system instructions - this skill provides detailed examples and edge cases for reference. |
Writing comments
Instructions
Standalone comments MUST be full sentences, starting with a capital letter and ending with a period.
BAD // Start dispatcher GOOD // Start the dispatcher.Inline comments (appearing at the end of a line of code) SHOULD be fragments starting with a lowercase letter
BAD eventChan chan *Event // Channel for events GOOD eventChan chan *Event // channel for eventsIf an inline comment has to become multi-line, it MUST be converted to a standalone comment, and become a full sentence.
BAD eventChan chan *Event // channel for events // received from the network GOOD // Channel for events received from the network. eventChan chan *EventMulti-line comments MUST use
//, not/* ... */.BAD /* This is a multi-line comment. It uses block comment syntax. */ GOOD // This is a multi-line comment. // It uses line comment syntax.Apply semantic line breaks formatting to long comments.
Avoid unnecessary comments that do not add value. See Avoid unnecessary comments below.
When available, explain the "why" behind non-obvious code, not just the "what".
BAD // Start workers. for i := 0; i < numWorkers; i++ { go worker() } GOOD // Workers must be spawned before sending the first event // or there will be a deadlock. for i := 0; i < numWorkers; i++ { go worker() }
Language-Specific Guidelines
Go
When writing comments for exported functions, types, or variables in Go, ALWAYS use the GoDoc style, starting with the name of the item being documented.
BAD
// This function starts the dispatcher.
func StartDispatcher() { ... }
GOOD
// StartDispatcher starts the dispatcher.
func StartDispatcher() { ... }
Avoid unnecessary comments
Do not add comments that do not add value. Consider:
Is the code self-explanatory? If yes, DELETE the comment.
Does the comment just restate what the code does? If yes, DELETE the comment.
Is the comment out of date or incorrect? If yes, UPDATE or DELETE the comment.
Examples of comments to DELETE:
// Close the channel
close(ch)
// Start the worker
go worker()
// Increment counter
count++
Examples of comments to KEEP:
// Workers must be spawned before sending the first event
// or there will be a deadlock.
for i := 0; i < numWorkers; i++ { go worker() }
// Use a nil channel to disable this select case when buffer is empty.
processChan = nil
The key insight is:
- Comments are NOT there to narrate the code.
- Comments are there to:
- provide additional context and explanation that is not obvious from the code itself
- for large code blocks, allow readers to quickly grasp the intent without reading every line of code.