self-explanatory-code-commenting
Guidance for writing code that explains itself, with fewer comments. Examples are in JavaScript; the rules apply to any language with comments.
- Kind
- Rules
- Works with
- GitHub Copilot
- Languages
- TypeScript / JavaScript
- Source
- Awesome Copilot @ d85f762d6e52
- Path
- instructions/self-explanatory-code-commenting.instructions.md
- License
- MIT
- Jobs
- Implementation
InstallCopy it from the source repository, or sign in and let the assistant adapt it for your project.
# 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**
```javascript
// Bad: States the obvious
let counter = 0; // Initialize counter to zero
counter++; // Increment counter by one
```
**Redundant Comments**
```javascript
// Bad: Comment repeats the code
function getUserName() {
return user.name; // Return the user's name
}
```
**Outdated Comments**
```javascript
// 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**
```javascript
// 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**
```javascript
// 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++) {
…