Global Commenting

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.

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.

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.

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.

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.

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.