{
    "slug": "missing_function_comments",
    "term": "Missing Function Comments",
    "category": "style",
    "difficulty": "beginner",
    "short": "Functions without PHPDoc lose IDE parameter hints, inline documentation, and the opportunity to explain non-obvious behaviour, preconditions, and edge cases.",
    "long": "In PHP 8 with full native type declarations, @param and @return are often redundant — the types speak for themselves. What is never redundant: a one-line summary of what the function does, @throws documentation for every exception that can propagate out, @deprecated for functions being phased out, and explanatory notes for any non-obvious preconditions or side effects. PHPStan and Psalm use PHPDoc for complex generics and templates that native types cannot express.",
    "aliases": [
        "missing PHPDoc method",
        "undocumented function",
        "no method comment"
    ],
    "tags": [
        "style",
        "php",
        "documentation",
        "phpdoc"
    ],
    "misconception": "Native PHP 8 type declarations make PHPDoc obsolete — @throws, complex generics (array<string, User>), and explanatory summaries cannot be expressed with native types alone.",
    "why_it_matters": "Missing @throws documentation means callers do not know they must handle an exception — undocumented exceptions cause unhandled exception crashes in production.",
    "common_mistakes": [
        "Omitting @throws for every exception that can escape the function.",
        "Repeating the method name as the docblock: /** getUserById */ — adds nothing.",
        "Not documenting preconditions: the caller must ensure X before calling this.",
        "Outdated docblocks after parameter types changed — wrong documentation is worse than none."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "docblock",
        "missing_class_comments",
        "code_documentation_standards"
    ],
    "prerequisites": [
        "docblock",
        "clean_code_naming",
        "type_declarations"
    ],
    "refs": [
        "https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/throws.html"
    ],
    "bad_code": "// No docblock — what does it throw? What are the constraints?\npublic function transfer(int $fromId, int $toId, float $amount)\n{\n    if ($amount <= 0) throw new InvalidArgumentException('Amount must be positive');\n    // Can throw DatabaseException, InsufficientFundsException...\n    $this->db->beginTransaction();\n    // ...\n}",
    "good_code": "/**\n * Transfers funds between two accounts atomically.\n *\n * @param int   $fromId Source account ID\n * @param int   $toId   Destination account ID\n * @param float $amount Positive amount in account currency\n *\n * @throws InvalidArgumentException  If amount is not positive\n * @throws InsufficientFundsException If source balance is insufficient\n * @throws DatabaseException          On transaction failure (rolled back)\n */\npublic function transfer(int $fromId, int $toId, float $amount): void",
    "quick_fix": "Add PHPDoc only when the method signature doesn't tell the whole story — complex @param types, @throws, or a non-obvious @return are valuable; don't duplicate what type declarations already express",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/missing_function_comments",
        "html_url": "https://codeclaritylab.com/glossary/missing_function_comments",
        "json_url": "https://codeclaritylab.com/glossary/missing_function_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 Function Comments](https://codeclaritylab.com/glossary/missing_function_comments) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/missing_function_comments"
            }
        }
    }
}