Global Commenting

Name: Global Commenting
Availability: InStock
Author: Devan

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

Updated Nov 15, 2025

Search Tags:#code quality #documentation #readability #maintainability #code comments #jsdoc #phpdoc

Ready to run

npx skills add https://github.com/DevanB/lucidlog --skill global-commenting-devanb

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill tackles the issue of outdated, redundant, or missing code comments that hinder understanding and maintainability. It promotes a philosophy of self-documenting code, ensuring comments are minimal, precise, and only used for complex logic, saving developers time deciphering code.

Core Features & Use Cases

Self-Documenting Code: Prioritizes clear naming and structure over excessive comments.
Targeted Commenting: Guides when and how to add comments for complex algorithms or business logic.
Use Case: When reviewing a complex PHP function, use this skill to ensure the AI adds PHPDoc blocks for parameters and return types, and only adds inline comments for non-obvious business logic, while removing any redundant comments.

Quick Start

Refactor the 'calculateDiscount' function to be more self-documenting and add PHPDoc comments only where necessary for complex 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 code comments that don't become outdated?▼

Evergreen comments focus on *why* code exists, not *what* it does. Document complex algorithms, business logic, and non-obvious decisions; let clear naming and structure speak for the rest. Remove comments that duplicate readable code, keeping only those that explain intent or constraints that aren't self-evident.

When should I add PHPDoc or JSDoc blocks to my code?▼

Add PHPDoc or JSDoc blocks to document function parameters, return types, and exceptions, especially for public APIs or complex logic. These blocks provide IDE autocomplete and type hints. Skip them for trivial getters or one-liners; focus on functions that need external context to understand.

What's the best way to make code self-documenting?▼

Self-documenting code uses clear variable and function names, logical structure, and minimal comments. Name functions for their purpose ('calculateMonthlyDiscount' not 'calc'), use descriptive variable names, and organize logic into small, focused functions. This reduces the need for explanatory comments while improving readability.

How do I balance having enough comments without cluttering code?▼

Comment only where code is genuinely unclear: complex algorithms, counterintuitive workarounds, or domain-specific business rules. Skip comments on obvious loops, standard patterns, or readable variable names. Review regularly to remove comments that no longer add value, keeping your codebase maintainable.

Can I apply commenting standards across different languages like PHP and JavaScript?▼

Yes. Core principles—documenting intent, avoiding redundancy, using type hints via PHPDoc or JSDoc—transfer across PHP, TypeScript, JavaScript, and other languages. Adapt syntax to each language's convention, but the philosophy of minimal, precise comments remains consistent.

Why should I remove outdated comments from my code?▼

Outdated comments mislead developers and erode trust in code. When comments contradict actual behavior, they waste time and introduce bugs. Regular review to remove stale comments keeps documentation accurate, reduces cognitive load, and ensures comments remain a reliable source of truth.