Missing Function Comments

Also Known As

TL;DR

Explanation

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.

Common Misconception

Why It Matters

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.

Code Examples

// No docblock — what does it throw? What are the constraints?
public function transfer(int $fromId, int $toId, float $amount)
{
    if ($amount <= 0) throw new InvalidArgumentException('Amount must be positive');
    // Can throw DatabaseException, InsufficientFundsException...
    $this->db->beginTransaction();
    // ...
}

/**
 * Transfers funds between two accounts atomically.
 *
 * @param int   $fromId Source account ID
 * @param int   $toId   Destination account ID
 * @param float $amount Positive amount in account currency
 *
 * @throws InvalidArgumentException  If amount is not positive
 * @throws InsufficientFundsException If source balance is insufficient
 * @throws DatabaseException          On transaction failure (rolled back)
 */
public function transfer(int $fromId, int $toId, float $amount): void

References

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

Tags

Related Terms