PHP 文档：如何编写不丢人的代码

你的代码胜于雄辩？不，如果你用 PHP 编写的话

想象一下：你打开一个半年前编写的旧 PHP 项目。你看着 processData() 函数，却……一无所知。什么数据？数据从何而来？为什么方法叫 doMagic()？熟悉吗？如果是，那么这篇文章就是为你准备的。

PHP 中的良好文档不仅仅是“对同事的礼貌”。它是你避免头痛的保险单，是加速新开发人员入职的利器，最终也是你产品质量的保证。在本文中，我们将探讨 PHP 代码文档的最佳实践，这些实践将把你混乱的代码转变为一个条理清晰、易于理解的系统。

为什么 PHP 文档不是“额外的工作”？

许多开发人员认为“好的代码不言自明”。这只有部分正确。好的代码解释了它如何工作，但很少解释为什么以及为何如此。文档填补了这些空白。它回答了以下问题：

\n
• 函数期望的输入数据是什么？
\n
• 出错时它返回什么？
\n
• 为什么做出这样的架构决策？
\n
• 方法有哪些副作用？
\n

如果没有这些问题的答案，你的代码就是一个黑匣子。而黑匣子即使是经验丰富的开发人员也不敢轻易触碰。

PHPDoc：你的主要工具

PHP 代码文档的事实标准是 PHPDoc。这是一种特殊的注释格式，以 /** 开头，以 */ 结尾。所有现代 IDE（PhpStorm、VS Code）以及文档生成工具（如 phpDocumentor 或 Doxygen）都支持它。

PHPDoc 的基本语法包括：

\n
• @param — 描述方法或函数的参数
\n
• @return — 返回值的类型和描述
\n
• @throws — 方法可能抛出的异常
\n
• @var — 类属性的类型
\n
• @see — 指向相关方法或类的链接
\n
• @deprecated — 标记功能已弃用
\n

一个好的 PHPDoc 块示例

<?php\n\n/**\n * 计算考虑折扣和税费后的最终订单金额。\n *\n * 此方法根据订单金额应用累进折扣率。\n * 如果金额超过 10,000 卢布，则应用最高 15% 的折扣。\n *\n * @param float $basePrice 不含折扣的订单基础金额（以卢布计）。\n * @param float $taxRate   税率，例如 0.20 表示 20%。\n * @param string $currency 用于格式化结果的货币（默认为 'RUB'）。\n *\n * @return string 包含最终金额的格式化字符串，例如 "12 500.00 ₽"。\n *\n * @throws \\InvalidArgumentException 如果基础金额为负数。\n * @throws \\RuntimeException         如果无法获取货币汇率。\n *\n * @see \\PriceCalculator::applyDiscounts() 了解折扣计算的详细信息。\n */\npublic function calculateFinalPrice(float $basePrice, float $taxRate, string $currency = 'RUB'): string\n{\n    if ($basePrice < 0) {\n        throw new \\InvalidArgumentException('基础金额不能为负数。');\n    }\n    // ... 计算逻辑\n}

请注意：我们不仅列出了类型，还解释了上下文（累进折扣率）、格式（格式化字符串）和边界条件（异常）。这才是高质量的文档。

最佳实践：从简单到复杂

1. 记录公共 API，不要动 private

不需要为每个私有的 getter 或 setter 编写 PHPDoc。IDE 已经可以看到类型。专注于公共接口的文档。