skills.rest
dpietersz
dpieterszCOMMUNITY
Explore all skills by this author →
GitHub

Global Commenting

Add concise, evergreen comments explaining non-trivial logic in any programming language.

Updated Jan 15, 2026
Search Tags:#documentation#commenting#maintenance#code-quality#best-practices#naming#self-documenting
One-click install
npx skills add https://github.com/dpietersz/pietersz.me --skill global-commenting-dpietersz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Global Commenting
Source: https://github.com/dpietersz/pietersz.me/tree/main/.claude/skills/global-commenting
Command: npx skills add https://github.com/dpietersz/pietersz.me --skill global-commenting-dpietersz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Write self-documenting code with minimal, helpful comments that explain complex logic without documenting temporary changes or fixes. This skill helps maintain readability and intent as code evolves.

Core Features & Use Cases

  • Self-documenting: Adds concise, durable comments that illuminate complex logic without clutter.
  • Language-agnostic: Applies to all major languages (JS, TS, Python, Ruby, Java, Go, PHP, and more) for functions, classes, and modules.
  • Review & maintenance: Helps identify outdated or temporary notes during reviews and refactors, ensuring comments stay relevant.

Quick Start

Comment a non-trivial function with a concise explanation of the algorithm and its intent.

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 with clear comments for complex logic?▼

Self-documenting code relies on descriptive naming and structure, adding concise, evergreen comments only to explain non-trivial algorithms and design intent. This approach minimizes clutter and maintains readability as code evolves.

What is the best way to maintain code comments during refactoring and maintenance?▼

The best way to maintain comments during refactoring is to enforce minimal, intent-focused documentation. This involves removing temporary notes and outdated explanations, ensuring comments stay relevant and accurately describe non-obvious logic.

Can I use this commenting approach for any programming language like Python or JavaScript?▼

Yes, this language-agnostic commenting approach applies to all major programming languages including JS, TS, Python, Ruby, Java, Go, and PHP. It helps document functions, classes, and modules regardless of the specific tech stack.

When should I avoid adding comments to my code?▼

You should avoid adding comments when the code is already self-explanatory through descriptive naming. Additionally, skip documenting temporary changes, quick fixes, or stale notes that will quickly become outdated and clutter the codebase.

How do I review code to identify outdated or temporary notes?▼

Review code for outdated notes by checking if comments explain durable intent rather than temporary fixes. Identify and remove stale annotations that no longer reflect the underlying non-trivial logic or current design decisions during maintenance.

Related Skills

Explore More Software Engineering Skills→
mrp4stenmrp4sten
3

clean-code

Apply Clean Code principles to improve code readability and maintainability.

Community
Advanced
DevanBDevanB

Global Commenting

Add minimal evergreen comments and PHPDoc or JSDoc blocks across code files.

Community
Basic
TorbenMerraldTorbenMerrald
1

Global Commenting

Guide developers to add concise, evergreen code comments explaining intent.

Community
Intermediate
mgoodman60mgoodman60

docs

Generate structured documentation from JavaScript/TypeScript codebases using inline comments and type definitions.

Community
Intermediate