github-copilot-instructions self-explanatory-code-commenting.instructions.md

Self-explanatory Code Commenting Instructions

Core Principle

Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT. We do not need comments most of the time.

Commenting Guidelines

❌ AVOID These Comment Types

Obvious Comments

// Bad: States the obvious
let counter = 0;  // Initialize counter to zero
counter++;  // Increment counter by one

Redundant Comments

// Bad: Comment repeats the code
function getUserName() {
    return user.name;  // Return the user's name
}

Outdated Comments

// Bad: Comment doesn't match the code
// Calculate tax at 5% rate
const tax = price * 0.08;  // Actually 8%

✅ WRITE These Comment Types

Complex Business Logic

// Good: Explains WHY this specific calculation
// Apply progressive tax brackets: 10% up to 10k, 20% above
const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);

Non-obvious Algorithms

// Good: Explains the algorithm choice
// Using Floyd-Warshall for all-pairs shortest paths
// because we need distances between all nodes
for (let k = 0; k < vertices; k++) {
    for (let i = 0; i < vertices; i++) {
        for (let j = 0; j < vertices; j++) {
            // ... implementation
        }
    }
}

Regex Patterns

// Good: Explains what the regex matches
// Match email format: [email protected]
const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

API Constraints or Gotchas

// Good: Explains external constraint
// GitHub API rate limit: 5000 requests/hour for authenticated users
await rateLimiter.wait();
const response = await fetch(githubApiUrl);

Decision Framework

Before writing a comment, ask:

1. Is the code self-explanatory? → No comment needed
2. Would a better variable/function name eliminate the need? → Refactor instead
3. Does this explain WHY, not WHAT? → Good comment
4. Will this help future maintainers? → Good comment