commenting-code

Code Commenting Rules

Decision Rule

If information can be extracted from code (function name, parameters, types, return type), the comment is USELESS. If it explains WHY, documents for non-developers (UI), or warns about non-obvious behavior, KEEP IT.

❌ REMOVE - Useless Comments

1. Visual Separator Comments

# =============================================================================
# Section Name
# =============================================================================

Noise. Code structure should be self-evident from organization.

2. Single-line Docstrings Repeating Signature

def enable(self, user: str | None = None) -> None:
    """Enable this ingestor configuration."""  # REMOVE

def get(self, config_id: UUID) -> IngestorConfig | None:
    """Get an ingestor config by its ID."""  # REMOVE

def delete(self, config_id: UUID) -> bool:
    """Delete an ingestor config by ID. Returns True if deleted."""  # REMOVE

Function name + parameters + return type already tell the story.

3. Comments Stating WHAT Code Does

# Loop through items  # REMOVE
for item in items:
    process(item)

Code already shows this.

✅ KEEP - Useful Comments

1. Django help_text on Model Fields

enabled = models.BooleanField(
    help_text="Whether this ingestor is active"  # KEEP
)

UI documentation for admin users, not developer comments. Serves runtime purpose.

2. Contract/Interface Documentation

class IngestorConfigRepository(ABC):
    """
    Repository interface for IngestorConfig persistence.

    Returns Django models directly (no mapping layer).
    """  # KEEP

Guides implementers. Documents design decisions and constraints.

3. WHY Explanations

# Minimum 60s to avoid API rate limiting  # KEEP
if poll_interval_seconds < 60:
    raise ValueError(...)

Intent not obvious from code alone.

4. Side Effects / Warnings

def update_cursor(self, new_cursor: str | None) -> None:
    # Also resets error_count and last_error_message  # KEEP

Non-obvious behavior that callers should know.

5. Business Rules

# Health thresholds: 0 = healthy, 1-4 = warning, 5+ = failing  # KEEP

Domain knowledge not evident from code.

6. Multi-line Class Docstrings with Value

class IngestorService:
    """
    Orchestrates ingestor execution.

    Responsibilities:
    - Execute ingestion cycles (polling mode)
    - Test external connections
    - Track run history and metrics
    """  # KEEP - explains purpose and responsibilities

7. NOTE/WARNING Comments

# NOTE: This admin is NOT registered by default.
# Raw events have short retention (14 days).  # KEEP

Important warnings for developers.

Quick Test

Before writing or reviewing a comment, ask:

1. Can I get this info from the function signature? → REMOVE
2. Does it explain WHY, not WHAT? → KEEP
3. Is it for end users (help_text, admin UI)? → KEEP
4. Does it warn about non-obvious behavior? → KEEP
5. Is it just visual decoration? → REMOVE

Usage

This skill activates when:

• Reviewing code comments for quality
• Cleaning up docstrings
• Checking if comments add value
• Refactoring code documentation

Apply these rules to identify and remove useless comments while preserving meaningful documentation.