---
name: clean-comments
description: Use when writing, fixing, editing, or reviewing TypeScript comments and TSDoc. Enforces Clean Code principles—no metadata, no redundancy, no commented-out code.
when_to_use: |
  Also trigger on: commented-out code blocks, TODO/FIXME banners, author/ticket/date metadata in comments, docstrings that no longer match the code, redundant comments that restate the code (e.g. `i += 1  # increment i`), or asks like "is this comment useful", "why is this block commented".
title: clean-comments
canonical_url: https://skilld.dev/gh/ertugrul-dmr/clean-code-skills/clean-comments
last_updated: 2026-09-28T08:45:29.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install ertugrul-dmr/clean-code-skills/clean-comments`. Install writes the Skill files into the project, so every session loads them.

# Clean Comments

## C1: No Inappropriate Information

Comments shouldn't hold metadata. Use Git for author names, change history, 
ticket numbers, and dates. Comments are for technical notes about code only.

## C2: Delete Obsolete Comments

If a comment describes code that no longer exists or works differently, 
delete it immediately. Stale comments become "floating islands of 
irrelevance and misdirection."

## C3: No Redundant Comments

```python
# Bad - the code already says this
i += 1  # increment i
user.save()  # save the user

# Good - explains WHY, not WHAT
i += 1  # compensate for zero-indexing in display
```

## C4: Write Comments Well

If a comment is worth writing, write it well:
- Choose words carefully
- Use correct grammar
- Don't ramble or state the obvious
- Be brief

## C5: Never Commit Commented-Out Code

```python
# DELETE THIS - it's an abomination
# def old_calculate_tax(income):
#     return income * 0.15
```

Who knows how old it is? Who knows if it's meaningful? Delete it. 
Git remembers everything.

## The Goal

The best comment is the code itself. If you need a comment to explain 
what code does, refactor first, comment last.