Missing Class Comments
debt(d3/e1/b3/t5)
Closest to 'default linter catches the common case' (d3). The detection_hints list phpcs, phpmd, and phpstan — all standard PHP tooling that ships with most PHP project setups. phpcs with PSR-12 or a documentation sniff will flag missing class docblocks as part of a routine CI run, placing this squarely at d3.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix explicitly says 'Add a one-line PHPDoc comment to public-facing classes.' Writing a brief docblock is a trivial, localised edit requiring no refactoring or cross-file changes.
Closest to 'localised tax' (b3). Missing comments impose a cost on the specific class being read — developers must read the full implementation to understand intent — but the rest of the codebase is largely unaffected. It is a persistent but contained friction rather than a systemic architectural weight.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field states directly: 'Self-documenting class names remove the need for comments — a class name identifies what it is; a docblock explains why it exists and any non-obvious design decisions.' Most developers have held this belief at some point, and the common_mistakes reinforce secondary traps (empty docblocks, restating the class name), making this a well-documented but frequently misunderstood concept.
Also Known As
TL;DR
Explanation
Class-level PHPDoc should describe what the class represents, its responsibilities, and any non-obvious design decisions. At minimum: a one-line summary. For complex classes: a longer description, @see references, usage examples, and @deprecated notices. PHPDoc blocks are parsed by IDE inspectors, phpDocumentor, and static analysers. In PHP 8 with native types, many @param and @return tags are redundant, but class-level descriptions remain valuable.
Common Misconception
Why It Matters
Common Mistakes
- Empty docblocks with only /** */ and no content — worse than nothing, implies documentation was started and abandoned.
- Docblocks that restate the class name: /** Class UserRepository */ — add real information.
- Missing @deprecated tag on classes that should no longer be used.
- Out-of-date docblocks that describe the old behaviour after refactoring.
Code Examples
<?php
namespace App\Repository;
// No docblock — IDEs show nothing on hover
class UserRepository
{
// ...
}
// Or useless docblock:
/**
* Class UserRepository
*/
class UserRepository { }<?php
namespace App\Repository;
/**
* Retrieves and persists User aggregates using PDO.
*
* All queries use prepared statements. Soft-deleted users
* are excluded unless withTrashed() is called first.
*
* @see User
*/
class UserRepository
{
// ...
}