{
    "slug": "docblock",
    "term": "PHPDoc / Docblock",
    "category": "style",
    "difficulty": "beginner",
    "short": "Structured comment blocks that document functions, classes, and properties — read by IDEs, static analysis tools, and documentation generators.",
    "long": "PHPDoc docblocks (/** ... */) use tags like @param, @return, @throws, @var, @property, @template, and @deprecated to annotate code. IDEs (PhpStorm, VS Code with Intelephense) use them for autocomplete and type inference; tools like PHPStan and Psalm use them for advanced static analysis; phpDocumentor generates API documentation from them. With modern PHP's native type declarations, many @param and @return tags are redundant — use them to add context, describe array shapes, or document generic types not expressible in PHP's type system.",
    "aliases": [
        "PHPDoc block",
        "PHP docblock",
        "doc comment"
    ],
    "tags": [
        "style",
        "php",
        "documentation",
        "static-analysis"
    ],
    "misconception": "PHPDoc blocks are redundant once PHP has native type declarations. Docblocks add information native types cannot express — @throws for exception contracts, @template for generics, complex union types in PHP 7, and @var for inline variable annotation used by IDEs and static analysers.",
    "why_it_matters": "PHPDoc docblocks provide machine-readable type information and documentation — IDEs use them for autocompletion, static analysers use them for type inference, and developers use them for understanding intent.",
    "common_mistakes": [
        "Docblocks that restate the type declarations already visible in the signature — zero added value.",
        "Missing @throws tags — callers cannot know which exceptions to handle.",
        "@param with no description for non-obvious parameters — the type is already in the declaration.",
        "Outdated docblocks that contradict the current code — worse than no docblock."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "psr_12",
        "naming_conventions",
        "attributes"
    ],
    "prerequisites": [
        "code_documentation_standards",
        "static_analysis",
        "phpstan_levels"
    ],
    "refs": [
        "https://docs.phpdoc.org/3.0/guide/references/phpdoc/",
        "https://phpstan.org/writing-php-code/phpdoc-types"
    ],
    "bad_code": "/**\n * Get user\n * @param int $id The id\n * @return User The user\n */\npublic function getUser(int $id): User // Docblock adds nothing — all visible in signature\n\n// Valuable docblock:\n/**\n * Finds user by ID. Throws if not found because callers must handle absence explicitly.\n * @throws UserNotFoundException if no user with this ID exists\n * @throws DatabaseException on connection failure\n */",
    "good_code": "/**\n * Transfer funds between two accounts atomically.\n *\n * @param  Account $from      Source account — must have sufficient balance\n * @param  Account $to        Destination account\n * @param  Money   $amount    Amount to transfer — must be positive\n * @return Transfer           The completed transfer record\n * @throws InsufficientFundsException  If $from balance < $amount\n * @throws CurrencyMismatchException   If accounts use different currencies\n */\npublic function transfer(Account $from, Account $to, Money $amount): Transfer\n\n// Skip docblocks when types + names are already self-documenting:\npublic function findById(int $id): ?User {} // no docblock needed",
    "example_note": "Only document what types can't express: thrown exceptions, pre/post-conditions, non-obvious behaviour. Don't restate the signature.",
    "quick_fix": "Use PHPDoc @param, @return, @throws for complex types that PHP's native type system cannot express — for simple scalar types, prefer native type declarations over redundant docblocks",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/docblock",
        "html_url": "https://codeclaritylab.com/glossary/docblock",
        "json_url": "https://codeclaritylab.com/glossary/docblock.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": "[PHPDoc / Docblock](https://codeclaritylab.com/glossary/docblock) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/docblock"
            }
        }
    }
}