Clippy Fixes and Code Style Enforcement

When to Use

• After making code changes
• Fixing clippy warnings
• Ensuring comment punctuation consistency
• Enforcing module organization patterns
• Before creating commits
• When user says "run clippy", "fix style", "format code", "check lints", etc.

Instructions

Run these steps in order to enforce code quality and style standards:

Step 1: Run Clippy

Run clippy to catch linting issues:

./check.fish --clippy
# (runs: cargo clippy --all-targets)

Review and fix all warnings. For auto-fixable issues:

cargo clippy --all-targets --fix --allow-dirty

Common clippy categories:

• Correctness: Potential bugs and logic errors (must fix)
• Performance: Inefficient code patterns (should fix)
• Style: Idiomatic Rust patterns (should fix)
• Pedantic: Opinionated style (optional, review case-by-case)
• Complexity: Overly complex code (refactor if excessive)

Step 2: Enforce Comment Punctuation

Apply these punctuation rules to all comments (not rustdoc /// or //!, but regular // comments) in the git working tree:

Rule 1: Single-line Standalone Comments

Add a period at the end:

// This is a single line comment.

Rule 2: Multi-line Wrapped Comments (One Logical Sentence)

Period ONLY on the last line:

// This is a long line that wraps
// to the next line.

Rule 3: Multiple Independent Single-line Comments

Each gets its own period:

// First independent thought.
// Second independent thought.

How to Identify Wrapped vs Independent

Wrapped comments:

• The second line continues the grammatical structure of the first
• Reads as one sentence if combined

Independent comments:

• Each line could stand alone as a complete thought
• Separate sentences with distinct subjects

Step 3: Enforce Clean Imports (No Inline Absolute Paths)

Scan the changed files for any inline absolute paths (e.g., crate::Type, crate::function!) and replace them with proper use statements at the top of the file.

✅ Good:

use crate::{Size, Pos};

pub fn render(size: Size) -> Pos { ... }

❌ Bad:

pub fn render(size: crate::Size) -> crate::Pos { ... }

Note: Intra-doc links like /// [Type]: crate::Type are exempt from this rule and SHOULD use crate:: paths.

Step 4: Verify Module Organization

Review all mod.rs files in the git working tree and ensure they follow the patterns from the organize-modules skill:

Check for:

• ✅ Private modules with public re-exports (preferred pattern)
• ✅ Conditional visibility for docs/tests where needed: #[cfg(any(test, doc))]
• ✅ Rustfmt skip directive if manual formatting is needed
• ✅ Flat public API (avoid exposing internal structure)

If module organization doesn't follow patterns, invoke the organize-modules skill for guidance.

Step 5: Verify Documentation Quality

If working with rustdoc comments (/// or //!):

1. Reference-style links: Ensure backticked symbols use reference-style intra-doc links
2. Link placement: All reference-style links at bottom of comment block
3. Table formatting: Markdown tables properly aligned

If there are issues, invoke the write-documentation skill (or use /fix-intradoc-links command).

Step 5: Run Tests if Needed

If clippy fixes modify behavior or you're unsure about changes:

./check.fish --test
# (runs: cargo test --all-targets)

Use the Task tool or invoke_subagent with subagent_type='test-runner' and Model: "inherit" if tests fail.

Step 6: Final Code Formatting

Run cargo fmt to ensure consistent formatting:

cargo fmt --all

This applies:

• Consistent indentation (4 spaces)
• Line length limits (100 chars default)
• Spacing around operators and braces
• Import organization

Step 7: Enforce Clean Imports

Ensure that code does not use absolute inline paths like crate::Type or crate::CONSTANT inside function signatures or bodies. They must be cleanly imported via use statements at the top of the file.

Step 8: Handling Unwraps and Panics

When addressing clippy::unwrap_used violations or manually reviewing code that can mathematically never fail:

• Avoid .expect("..."). While .expect() provides a panic message at runtime, we prefer to keep string literals out of the logic flow for a cleaner aesthetic.
• Use #[allow(clippy::unwrap_used, reason = "...")] instead of .expect(). The reason should explicitly state the mathematical or logical proof for why the unwrap() is safe.
• Fallbacks: If the unwrap() is not mathematically proven safe and is truly fallible (e.g., file I/O), rewrite it using if let Ok() or propagate the error instead of panicking.

Step 9: Prefer ? Operator / Early Returns over .and_then() (Mandatory)

Do NOT use .and_then() for chaining Option or Result operations in code. Instead, write idiomatic Rust using early returns with the ? operator (or if let / let-else statements). The only acceptable exception is for boolean constant gating in tracing/logging calls if necessary, though even then, canonical Rust is preferred.

✅ Good:

fn get_char(&self, pos: Pos) -> Option<PixelChar> {
    let row = self.get_row(pos.row_index)?;
    let cell = row.get(pos.col_index.as_usize())?;
    Some(*cell)
}

❌ Bad:

fn get_char(&self, pos: Pos) -> Option<PixelChar> {
    self.get_row(pos.row_index)
        .and_then(|row| row.get(pos.col_index.as_usize()))
        .copied()
}

Reporting Results

After completing all steps, report concisely:

• ✅ All checks passed → "Code style and linting checks passed!"
• ⚠️ Clippy warnings → Summarize warning categories and counts
• 🔧 Auto-fixed → Report what was automatically corrected
• 📝 Manual fixes needed → List what requires developer attention

Supporting Files in This Skill

This skill includes additional reference material:

• patterns.md - Comprehensive examples of code style patterns including comment punctuation rules (20+ examples), clippy lint categories with fixes, cargo fmt formatting rules, and module organization quick checks. Read this when:
  • Need examples of proper comment punctuation (wrapped vs independent)
  • Understanding clippy lint categories (correctness, performance, style)
  • See good vs bad examples for specific lints
  • Quick module organization checks
  • Understanding cargo fmt rules (indentation, line length, imports)

Related Skills

• check-code-quality - Includes clippy as part of full quality checks
• organize-modules - For module organization patterns
• write-documentation - For rustdoc link formatting and comprehensive doc formatting

Related Commands

• /clippy - Explicitly invokes this skill
• /fix-comments - Focuses on comment punctuation (subset of this skill)

Related Agents

• clippy-runner - Agent that delegates to this skill