comment-style

Enforces terse, factual comment and docstring style in Python code reviews.

1|Updated May 13, 2026

Search Tags:#code review #documentation #python #style guide #code comments #docstrings

One-click install

npx skills add https://github.com/dlt-hub/dlthub-start --skill comment-style-dlt-hub

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: comment-style
Source: https://github.com/dlt-hub/dlthub-start/tree/main/.claude/skills/comment-style
Command: npx skills add https://github.com/dlt-hub/dlthub-start --skill comment-style-dlt-hub

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate verbose, generated-sounding comments that restate function names, narrate reasoning history, or describe alternatives considered, making code harder to scan and maintain. ## Core Features & Use Cases - Comment Quality Rules: Applies five concrete rules — delete redundant comments, cap length at two lines, state what not the story, match sibling style, and never restate self-describing names. - Keep-or-Drop Test: Provides a single decision test — keep a comment only if removing it would make a maintainer guess wrong about something not visible in the code. - Use Case: When reviewing a diff in the dlthub-start CLI codebase (src/create_dlthub_workspace/**), use this Skill to flag comments that narrate tradeoffs or restate parameter names like `stream=False`, and rewrite them into one-line factual statements. ## Quick Start Review the comments and docstrings in my latest diff and rewrite or delete any that violate the comment style rules.

Frequently Asked Questions about comment-style

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write good code comments in Python?▼

Keep comments terse and factual: state what the code does plus the one non-obvious why, in two lines or fewer. Delete any comment that restates the function name, parameters, or the line itself.

When should I delete a comment instead of rewriting it?▼

Delete a comment when the name, parameters, or the line already convey the same information. The test is whether removing it would make a maintainer guess wrong about something not visible in the code.

Should every Python function have a docstring?▼

No. Match the sibling style of the surrounding code — in this codebase private helpers usually have no docstring, so do not add one just because the function is new.

What makes a code comment low quality in review?▼

Low-quality comments narrate reasoning, tradeoffs, or history, list alternatives considered, or restate self-describing code like `stream=False`. Good comments state what the code does and one non-obvious why in a single line.