Global Commenting

Review code to enforce clear naming and minimal comments for complex logic.

6|1|Updated Nov 12, 2022

Search Tags:#code quality #best practices #documentation #refactoring #readability #maintainability #comments

Ready to run

npx skills add https://github.com/coreyja/coreyja.com --skill global-commenting-coreyja

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: Global Commenting
Source: https://github.com/coreyja/coreyja.com/tree/main/.claude/skills/global-commenting
Command: npx skills add https://github.com/coreyja/coreyja.com --skill global-commenting-coreyja

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill promotes writing self-documenting code and guides the strategic use of comments to explain complex logic, reducing confusion and improving code maintainability.

Core Features & Use Cases

Self-Documenting Code: Emphasizes clear naming and structure to minimize the need for extraneous comments.
Strategic Commenting: Guides when and how to add comments for non-obvious business logic or architectural decisions.
Use Case: When reviewing a complex algorithm, use this skill to ensure variable names are descriptive and only add comments to explain the 'why' behind specific, non-obvious steps, not the 'what'.

Quick Start

Use the Global Commenting skill to review the 'processOrder' function, ensuring variable names are clear and only add comments for the complex tax calculation logic.

Frequently Asked Questions about Global Commenting

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

FAQPage Schema

How do I write self-documenting code that reduces the need for comments?▼

Self-documenting code uses clear, descriptive variable and function names combined with explicit structure to convey intent without extraneous comments. Focus on naming that reveals purpose—`calculateTaxAmount` instead of `calc`—and organize logic into small, single-responsibility functions so the 'what' becomes obvious from reading the code itself.

When should I add comments to code, and what should they explain?▼

Add comments only to explain non-obvious business logic, complex algorithms, or architectural decisions—the 'why,' not the 'what.' Comment tax calculation edge cases or regex patterns that aren't immediately clear. Avoid narrating every line; let clean naming and structure speak for themselves.

Can I apply self-documenting code practices to all programming languages?▼

Yes. Self-documenting principles—clear naming, explicit structure, and strategic comments—apply across all programming languages and file types. Whether writing Python, Java, or JavaScript, the same practices improve readability and maintainability.

How do I review code for readability and maintainability issues?▼

Review code by checking that variable names are descriptive, functions have single purposes, and comments explain only complex or non-obvious logic. Refactor unclear naming, break apart tangled logic, and remove redundant comments that simply repeat what the code does.

What's the difference between comments that explain 'why' versus 'what'?▼

'What' comments repeat the code's action—redundant and harmful to maintenance. 'Why' comments justify design choices, business rules, or non-obvious approaches. Comments explaining 'why we calculate tax before discount' are valuable; comments restating `x = x + 1` waste space and go stale.

Does this approach work for refactoring existing code?▼

Yes. Apply self-documenting principles during refactoring by renaming variables for clarity, restructuring logic into smaller functions, and replacing obsolete comments with clearer code. This technique improves readability across new code, reviews, and maintenance tasks.