tomevault-io Code Commenting Guidelines
This skill provides a set of principles and patterns for writing code comments that are helpful, maintainable, and non-redundant.
Core Principles
- Explain the "Why", Not the "What": Code should ideally be self-documenting regarding what it is doing. Comments must focus on the rationale, technical intent, and constraints that are not immediately obvious from the code itself.
- Avoid Redundancy: Never write comments that merely restate what the code clearly says. If the code is complex, prioritize refactoring for clarity over adding a descriptive comment.
- Remove Obsolete Comments: When modifying code, always update or remove associated comments. Stale comments are worse than no comments.
- Documentation Blocks for Public APIs: Use formal documentation blocks (e.g., JSDoc, Docstrings) for public methods, classes, and complex internal interfaces. Focus on parameters, return values, and side effects.
- Use Inline Comments Sparingly: Use inline comments only for non-obvious hacks, workarounds, or business logic that requires specific context.
Commenting Patterns
1. Rationale Comments
Use these when a specific implementation choice was made for non-obvious reasons (e.g., performance, bug workaround).
// BAD: Increment counter
counter++;
// GOOD: Use a manual increment here instead of the utility function
// to avoid the overhead of the recursive check in hot loops.
counter++;
2. Implementation Warnings
Alert other developers to non-obvious side effects or fragile logic.
# GOOD: This function is not thread-safe because it shares a global state
# with the database connection pool. Ensure it's called within a lock.
def process_data():
...
3. API Documentation
Standardized blocks for interfaces.
/**
* Processes the incoming request and validates the signature.
*
* @param {Request} req - The raw HTTP request object.
* @throws {InvalidSignatureError} If the HMAC signature check fails.
* @returns {Promise<User>} The authenticated user object.
*/
async function authenticate(req) {
...
}
Anti-Patterns to Avoid
- The "Captain Obvious":
i++; // Increment i - The "History Log":
// Modified by John on 2021-05-21 to fix bug X(This belongs in Git history). - The "Zombie Code": Commented-out code blocks. Delete them; they are preserved in Git.
- The "Vague Directive":
// Fix this later(Always provide context or a ticket number).
Workflow
- Analyze the code: Identify non-obvious logic, business rules, or complex interfaces.
- Refactor first: If a comment is needed to explain what the code does, try to rename variables or extract methods first.
- Write the rationale: If the why is still unclear, add a concise comment.
- Choose the format: Use inline comments for logic, and blocks for APIs.
- Review for redundancy: Strip away any comments that add zero value to a senior developer reading the code.
Source: mostafa-ismail-2004/everything-agy — distributed by TomeVault.