{
    "slug": "missing_class_comments",
    "term": "Missing Class Comments",
    "category": "style",
    "difficulty": "beginner",
    "short": "A class without a PHPDoc block lacks the docblock description, @package annotation, and context needed for IDE tooling, generated documentation, and new developers.",
    "long": "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.",
    "aliases": [
        "missing PHPDoc",
        "no class comment",
        "undocumented class"
    ],
    "tags": [
        "style",
        "php",
        "documentation",
        "phpdoc"
    ],
    "misconception": "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.",
    "why_it_matters": "A class without a docblock makes IDEs show no hover documentation, makes phpDocumentor generate empty pages, and forces new developers to read the entire implementation to understand the class's purpose.",
    "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."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "docblock",
        "code_documentation_standards",
        "missing_function_comments"
    ],
    "prerequisites": [
        "docblock",
        "clean_code_naming",
        "documentation"
    ],
    "refs": [
        "https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/"
    ],
    "bad_code": "<?php\nnamespace App\\Repository;\n\n// No docblock — IDEs show nothing on hover\nclass UserRepository\n{\n    // ...\n}\n\n// Or useless docblock:\n/**\n * Class UserRepository\n */\nclass UserRepository { }",
    "good_code": "<?php\nnamespace App\\Repository;\n\n/**\n * Retrieves and persists User aggregates using PDO.\n *\n * All queries use prepared statements. Soft-deleted users\n * are excluded unless withTrashed() is called first.\n *\n * @see User\n */\nclass UserRepository\n{\n    // ...\n}",
    "quick_fix": "Add a one-line PHPDoc comment to public-facing classes describing the responsibility — not what it is (the class name says that) but what problem it solves and what it should NOT be used for",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/missing_class_comments",
        "html_url": "https://codeclaritylab.com/glossary/missing_class_comments",
        "json_url": "https://codeclaritylab.com/glossary/missing_class_comments.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Missing Class Comments](https://codeclaritylab.com/glossary/missing_class_comments) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/missing_class_comments"
            }
        }
    }
}