Missing Class Comments

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
{
    // ...
}

References

• ↗ https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/

Tags

Related Terms