From django-engineering
Use when writing, reviewing, or cleaning up code comments and docstrings in Python. Covers decisions about which comments to keep and which to remove.
How this skill is triggered — by the user, by Claude, or both
Slash command
/django-engineering:commenting-codeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **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.**
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.
# =============================================================================
# Section Name
# =============================================================================
Noise. Code structure should be self-evident from organization.
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.
# Loop through items # REMOVE
for item in items:
process(item)
Code already shows this.
enabled = models.BooleanField(
help_text="Whether this ingestor is active" # KEEP
)
UI documentation for admin users, not developer comments. Serves runtime purpose.
class IngestorConfigRepository(ABC):
"""
Repository interface for IngestorConfig persistence.
Returns Django models directly (no mapping layer).
""" # KEEP
Guides implementers. Documents design decisions and constraints.
# Minimum 60s to avoid API rate limiting # KEEP
if poll_interval_seconds < 60:
raise ValueError(...)
Intent not obvious from code alone.
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.
# Health thresholds: 0 = healthy, 1-4 = warning, 5+ = failing # KEEP
Domain knowledge not evident from code.
class IngestorService:
"""
Orchestrates ingestor execution.
Responsibilities:
- Execute ingestion cycles (polling mode)
- Test external connections
- Track run history and metrics
""" # KEEP - explains purpose and responsibilities
# NOTE: This admin is NOT registered by default.
# Raw events have short retention (14 days). # KEEP
Important warnings for developers.
Before writing or reviewing a comment, ask:
This skill activates when:
Apply these rules to identify and remove useless comments while preserving meaningful documentation.
npx claudepluginhub othercode/profiles --plugin django-engineeringEnforces guidelines for clean code comments: use sparingly, ban commented-out code and change descriptions, avoid end-of-line comments. Use when adding, editing, or removing comments.
Automatically generates documentation comments and docstrings for code functions/classes, matching project style or language conventions like Google/NumPy for Python, JSDoc for JS/TS, godoc for Go.
Audits code clarity and documentation quality using APOSD's obviousness rules. Covers naming quality, comment accuracy, AI-facing doc completeness, and a comments-first workflow for new code.