先探讨几个关键判断。独立开发者在用 PHP 编写个人库时，注释绝非可有可无的流程装饰，它本质上构成了这个库的“品牌资产”，也是未来他人（甚至未来的你）接手代码时的“协作接口”。真正的痛点在于，如何让每一处署名、每一个 @param、每段说明，都切实服务于同一个目标——让代码“可理解、可复用、可信任”。
文件头部统一声明：为整个库打上可靠标签
每个 PHP 文件的开头，都必须用 /** */ 包裹一个标准头部注释。其中应包含三项要素：库或模块名称、作者 ID（推荐直接使用 GitHub 用户名）、创建日期。不写邮箱、不加链接均可，但 ID 必须真实、可追溯——这是你技术身份的起点。
- 格式：必须以
/**开头，切勿使用/*或//，否则 IDE 和文档工具将无法识别。 - 描述：避免“用户模块”这类空泛说法，应改为“JWT 登录与会话续期核心逻辑”，含义一目了然。
- 日期：采用 YYYY-MM-DD 格式，例如 2026-06-15。这能帮助你在后续 Git 比对和版本回溯中节省大量时间。
函数级 PHPDoc：为调用者撰写说明书，而非为编译器
每个公开的函数、方法、类，都必须具备完整的 PHPDoc 块。重点不在于堆砌标签，而是说清边界与意图。@param 和 @return 是必须编写的，类型需准确，描述要简洁。
- 类型：
@param后跟原生小写类型，例如string、int、array，切勿写成String或Integer。 - 参数名：必须带
$，且大小写与函数定义完全一致。$userId和$userid是两回事。 - 返回值：需写明成功与失败情形。例如
@return array|false，而非简单写@return array。 - 特殊场景：遇到兼容旧版逻辑、绕过限制、临时 hack 的情况，直接在描述中说明原因。例如“兼容 v1.2 API 未返回 error_code 字段”——这比任何注释都更有效。
作者署名不炫技，只锚定关键决策点
在个人库中署名，并非每行都标注 @author。真正有价值的做法是：在体现技术判断的位置，添加一个轻量标记。这能帮助未来的你在回溯时快速定位“这段当时我是怎么想的”。
- 函数 DocBlock 中使用
@author leo-wang（紧贴其他标签，不单独成块）。 - 算法替换、加密方案升级、性能重构等重大变更处，添加一行
// Refactored by leo-wang, 2026-06-18。 - 小修小补（如修复拼写错误、调整超时数值、补全缺失的 return）不必署名，这些交给 Git commit 记录更为合适。
自动化保底：模板 + 钩子，让规范不依赖自觉
完全靠手写难免遗漏，特别是在新建文件或深夜赶工时。借助编辑器模板和 Git 钩子将基础动作固化下来，才是稳妥的做法。
- 在 VS Code 或 PHPStorm 中配置文件头 snippet。新建
.php文件时，自动插入预设的作者和日期。 - 在
pre-commit脚本中添加一道检查：新 PHP 文件是否包含以/**开头的头部注释。若缺失，提示警告但不阻断提交。 - 不强求所有函数都具备完整的
@param，但至少公共 API 入口和核心类构造方法必须达到标准。
