| name | effective-commenting-strategies |
| description | Use this skill when writing, reviewing, or maintaining code comments. Apply these strategies to ensure comments explain intent rather than repeat code, use maintainable styles, and follow density guidelines. This skill covers comment types, style best practices, and performance considerations. |
Effective Commenting Strategies
Good comments explain the "why" behind code, not the "what." Use these strategies to write comments that enhance code maintainability without creating maintenance burden.
When to Use
- Adding comments to new code
- Reviewing existing comments for quality
- Establishing team commenting standards
- Optimizing comment density for readability
- Handling performance-sensitive code with comments
Core Principle: Intent Over Repetition
Good comments should:
- Not repeat code or explain what the code does
- Clarify intent at a higher abstraction level than the code
- Act as navigation like book headings or table of contents
- Help maintenance by explaining the original programmer's intent
- **Be efficient"—reading one English comment is faster than parsing 20 lines of code
Rule: If the code already explains everything, a comment that repeats it provides no value.
Comment Types
Marker Comments
Purpose: Remind developers of incomplete work (not intended for production)
Requirements:
- Use standardized markers (e.g.,
***, TBD, TODO)
- Make markers mechanically searchable
- Include in release checklist to prevent shipping known defects
Action: Search for all markers before release to ensure no incomplete code ships.
Explanatory Comments
Purpose: Explain complex, tricky, or sensitive code
Strategy:
- If code is complex enough to need explanation, refactor the code first
- Make the code itself clearer
- Then use summary or intent comments if still needed
Summary Comments
Purpose: Condense several lines of code into one or two sentences
Value: More valuable than code-repeating comments because readers can scan them faster than reading code
When to use: Particularly helpful when non-original authors need to modify code
Intent Comments
Purpose: Explain the purpose of a code section at the intent/problem level
Level: Operates more at the problem level than the solution level
Example:
- Intent: "Get current employee information"
- Solution/Summary: "Update employeeRecord object"
Metadata Comments
Purpose: Record information that cannot be expressed in code
Includes:
- Copyright notices
- Confidentiality statements
- Version numbers
- Design notes
- Requirement references
- Online reference pointers
- Optimization notes
- Tool-required comments (e.g., Javadoc)
Maintainable Comment Style
Avoid High-Maintenance Styles
Do not use styles that require manual alignment:
- ❌ Leader dots (
...) connecting variables and descriptions
- ❌ Asterisk boxes (
*) surrounding paragraphs—requires adjusting both sides
- ❌ Plus-sign underlines (
+---+)—requires precise positioning when text length changes
Principle: Prefer accurate comments over pretty comments. If maintaining aesthetics requires tedious work, abandon that style.
Syntax Guidelines
For Java and C++:
- Single-line comments: Use
// syntax, keep comments short
- Multi-line comments: Use
/* ... */ syntax—easier to maintain than manually wrapped // lines
For emphasis: Use standard-length lines (via editor macros), not lines that vary with comment length
Comment Density Guidelines
Optimal Density
IBM Research Finding: Approximately 1 comment per 10 statements maximizes code clarity
- Below this density: Code becomes difficult to understand
- Above this density: Readability decreases
Avoid Quotas
Do not enforce rigid standards like "at least 1 comment per 5 lines"
Reason: This addresses the symptom (lack of comments) without solving the root cause (unclear code)
Performance Considerations
Principle: Do not avoid comments due to performance concerns (e.g., interpreted environments, network transmission overhead)
Solution: Create a separate release build
Implementation: Run a tool during the build process to automatically strip comments from the production version
Pseudocode Programming Process (PPP) Comment Efficiency
When using the Pseudocode Programming Process:
- Recognize the pattern: Effective PPP naturally results in "a comment every few lines"
- Understand the nature: Comment quantity is a side effect of the process, not a goal
- Focus on efficiency: Don't count comments—evaluate whether each comment is effective
- Assess sufficiency: Comments are sufficient if they:
- Describe why the code was written
- Meet the other standards in this skill
Conclusion: If comments explain "why" and meet quality standards, the quantity is adequate—don't worry about the number.
