Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/clean-code-comments

clean-code-comments

Verified

Remove or shorten redundant source-code comments without changing behavior. Use for explicit comment cleanup or dry audits of user-specified files and directories; do not use for general refactoring, documentation generation, or generated-output cleanup.

FileKindSize
SKILL.mdskill md5.9 KB
agents/openai.yamlconfig284 B
references/comment-policy.mdmarkdown5.4 KB
references/examples.mdmarkdown7.8 KB

references/examples.md

View on GitHub
# Comment Cleanup Examples

Use these examples when the correct treatment of a comment is unclear.

The examples illustrate intent. Apply repository and language conventions before copying any pattern.

## Contents

- [Obvious narration](#obvious-narration)
- [Redundant initialization comments](#redundant-initialization-comments)
- [Redundant function documentation](#redundant-function-documentation)
- [Redundant constant documentation](#redundant-constant-documentation)
- [Comments describing transformations](#comments-describing-transformations)
- [Preserve external behavior](#preserve-external-behavior)
- [Replace implementation narration with rationale](#replace-implementation-narration-with-rationale)
- [Shorten verbose rationale](#shorten-verbose-rationale)
- [Preserve operation ordering](#preserve-operation-ordering)
- [Preserve retry and idempotency context](#preserve-retry-and-idempotency-context)
- [Preserve security constraints](#preserve-security-constraints)
- [Preserve compatibility workarounds](#preserve-compatibility-workarounds)
- [Preserve concurrency assumptions](#preserve-concurrency-assumptions)
- [Decorative sections](#decorative-sections)
- [Tooling directives](#tooling-directives)
- [TODO markers](#todo-markers)
- [Commented-out code](#commented-out-code)
- [Mixed useful and redundant content](#mixed-useful-and-redundant-content)
- [Final classification check](#final-classification-check)

## Obvious narration

### Go

Before:

```go
// Increment the counter.
counter++

// Return the result.
return result
```

After:

```go
counter++
return result
```

Before:

```go
// Check if the error is not nil.
if err != nil {
	return err
}
```

After:

```go
if err != nil {
	return err
}
```

## Redundant initialization comments

### Python

Before:

```python
# Initialize an empty list.
results = []
```

After:

```python
results = []
```

### TypeScript

Before:

```typescript
// Create a new user.
const user = new User();
```

After:

```typescript
const user = new User();
```

### PHP

Before:

```php
// Loop through all items.
foreach ($items as $item) {
    process($item);
}
```

After:

```php
foreach ($items as $item) {
    process($item);
}
```

## Redundant function documentation

Before:

```go
// GetUser gets a user by ID.
func GetUser(id string) (*User, error) {
	return repository.Find(id)
}
```

When exported documentation is not required:

```go
func GetUser(id string) (*User, error) {
	return repository.Find(id)
}
```

When exported documentation is required and non-obvious behavior exists:

```go
// GetUser returns ErrUserNotFound when no active user has the given ID.
func GetUser(id string) (*User, error) {
	return repository.Find(id)
}
```

Do not invent the error behavior merely to retain a comment.

## Redundant constant documentation

Before:

```go
// DefaultTimeout is the default timeout.
const DefaultTimeout = 30 * time.Second
```

After:

```go
const DefaultTimeout = 30 * time.Second
```

When the value reflects an external constraint:

```go
// DefaultTimeout matches the gateway's maximum request duration.
const DefaultTimeout = 30 * time.Second
```

## Comments describing transformations

Before:

```go
// Convert the string to lowercase.
normalized := strings.ToLower(value)

// Remove whitespace.
normalized = strings.TrimSpace(normalized)
```

After:

```go
normalized := strings.ToLower(value)
normalized = strings.TrimSpace(normalized)
```

## Preserve external behavior

Preserve:

```go
// The provider retries webhooks, so the payment may already exist.
```

The local code may check for an existing payment, but the comment explains why duplicate delivery is expected.

## Replace implementation narration with rationale

Before:

```go
// Sleep for 100 milliseconds.
time.Sleep(100 * time.Millisecond)
```

When the delay has no non-obvious documented reason:

```go
time.Sleep(100 * time.Millisecond)
```

When an external constraint exists:

```go
// The upstream API rejects retries within the same 100 ms window.
time.Sleep(100 * time.Millisecond)
```

## Shorten verbose rationale

Before:

```go
// We need to sort the records by creation time here because the external
// reporting API expects all records to be sent in chronological order,
// otherwise the API can produce incorrect cumulative totals in its reports.
sort.Slice(records, lessByCreatedAt)
```

After:

```go
// Reporting totals require records in chronological order.
sort.Slice(records, lessByCreatedAt)
```

## Preserve operation ordering

Preserve:

```go
// Delete children first because this database does not enforce cascading deletes.
```

The code shows the order, but not why changing the order would be unsafe.

## Preserve retry and idempotency context

Preserve:

```go
// Mark the request complete only after publishing succeeds; the worker may retry.
```

Do not replace it with:

```go
// Publish the event and mark the request complete.
```

The replacement narrates the code and removes the important retry invariant.

## Preserve security constraints

Preserve:

```go
// Compare hashes in constant time to avoid leaking signature information.
```

Do not shorten it to:

```go
// Compare hashes.
```

## Preserve compatibility workarounds

Preserve:

```typescript
// Safari 15 reports zero height until the next animation frame.
requestAnimationFrame(measure);
```

A possible shorter version is:

```typescript
// Safari 15 reports zero height before the next animation frame.
requestAnimationFrame(measure);
```

## Preserve concurrency assumptions

Preserve:

```go
// Only the lease holder may update this record.
```

Do not remove it merely because the surrounding condition checks a lease identifier.

## Decorative sections

Before:

```go
// Validate
if err := validate(input); err != nil {
	return err
}

// Process
result := process(input)

// Return result
return result
```

After:

```go
if err := validate(input); err != nil {
	return err
}

result := process(input)
return result
```

Keep section comments in long files only when they materially improve navigation and match repository conventions.

## Tooling directives

Preserve without rewriting:

```go
//go:build linux
```

```go
//go:generate mockgen -source=client.go
```

```typescript
// eslint-disable-next-line @typescript-eslint/no-explicit-any
```

```python
# type: ignore[arg-type]
```

```php
/** @phpstan-ignore-next-line */
```

Do not convert tool directives into prose.

## TODO markers

Preserve:

```go
// TODO: Remove legacy parsing after mobile clients below v4 are unsupported.
```

Remove when clearly valueless:

```go
// TODO: Improve this.
```

Do not turn it into a fabricated task such as:

```go
// TODO(PROJ-123): Replace this with the new parser by Q4.
```

unless those details already exist in the repository.

## Commented-out code

Before:

```go
// oldClient.Send(request)
newClient.Send(request)
```

After, when the old line is clearly obsolete:

```go
newClient.Send(request)
```

Preserve commented-out code when it belongs to a fixture or intentionally documented example:

```go
// Use insecureTransport only in local integration tests.
// client := NewClient(insecureTransport)
```

## Mixed useful and redundant content

Before:

```go
// Check whether the payment already exists because the payment provider
// retries webhook requests multiple times whenever it does not receive a
// successful HTTP response from our endpoint.
if repository.Exists(paymentID) {
	return nil
}
```

After:

```go
// Provider retries can deliver the same payment more than once.
if repository.Exists(paymentID) {
	return nil
}
```

## Final classification check

Before editing a comment, determine whether it primarily describes:

* **what the next line does** — usually remove;
* **why the code must behave this way** — usually preserve;
* **a useful constraint in too many words** — shorten;
* **tool metadata or a directive** — preserve;
* **unknown domain or tooling behavior** — preserve and report if material.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall