php包含文件注释应写在include/require语句上方，明确路径来源与用途；推荐用// include: dir . '/path'格式，避免模糊缩写；@see标记需用相对路径以支持ide跳转；注释不可写入引号内，多行拼接须注释于语句外；define路径常量的注释应放在定义处；phpdocumentor不解析include注释，依赖关系需靠静态分析工具识别。
PHP中包含文件的注释要写在include或require语句上方，且必须说明路径来源和用途
PHP本身不强制要求为include类语句加注释，但团队协作或维护老项目时，没注释的require_once 'config.php';很容易让人卡住——这文件是相对路径？从vendor加载的？还是通过set_include_path()注入的？
实际踩坑最多的是：注释写了但路径描述模糊，比如只写// 加载数据库配置，却没提config/database.php是相对于当前文件、入口脚本，还是__DIR__拼接出来的。
- 推荐写法：
// include: __DIR__ . '/lib/Cache.php' —— 本地缓存工具类，非Composer包 - 避免写法：
// 引入缓存（太泛）、// config（缩写歧义大） - 如果路径含变量或函数调用（如
dirname(__FILE__) . '/core/init.php'），注释里必须还原成可读路径逻辑，例如：// require: CORE_PATH . '/init.php' → 实际加载 /var/www/app/core/init.php
用/** @see */ PHPDoc 标记关联被包含文件（IDE友好但非运行必需）
PHPStan、PHPStorm 等工具能识别@see标记并跳转到目标文件，这对大型项目查依赖链很有用。但它只是提示性注释，不影响执行，也不校验路径是否存在。
/** * 初始化应用环境 * @see ../config/environment.php * @see ../vendor/autoload.php */ require_once __DIR__ . '/../config/environment.php'; require_once __DIR__ . '/../vendor/autoload.php';
-
@see后面建议写相对路径（以当前文件为基准），方便IDE解析；绝对路径或变量拼接路径（如@see CONFIG_DIR . '/db.php'）多数工具无法跳转 - 不要滥用：
@see适合关键入口或配置文件，日常include 'Utils/StringHelper.php';没必要加 - 注意斜杠方向：Windows下反斜杠
\在PHPDoc里会被当转义符，统一用正斜杠/
别把注释写进include路径字符串里——这是常见语法错误
有人为了“一行搞定”，把注释硬塞进引号里：include 'functions.php'; // 加载核心函数，这没问题；但写成include 'functions.php // 加载核心函数';就直接报错Warning: include(): Failed opening 'functions.php // 加载核心函数' for inclusion。
- 路径字符串内不能含任何注释字符（
//、/*、#），PHP会当字面量处理 - 多行路径拼接时，注释只能放在拼接语句外：
// 拼接规则：先取父目录，再进 lib 子目录$path = dirname(__DIR__) . '/lib/Log.php';require $path; - 用
define()或const管理路径常量时，注释应放在定义处，而非include调用处
生成文档时，phpDocumentor 不解析include语句——注释不会出现在API文档里
即使你给require_once 'Router.php';写了三行PHPDoc，phpDocumentor默认也不会把它当“引用关系”收录进文档结构。它只扫描函数、类、常量、属性等声明式元素。
立即学习“PHP免费学习笔记（深入）”；
- 想让依赖关系可视化，得靠静态分析工具（如PHPStan的
--debug模式、Psalm的--find-dead-code）或构建流程插件（如Composer的autoload-dev映射） - 如果项目用Sami或phpDocumentor自动生成文档，需手动在
index.md或@package注释块里说明模块间包含关系 - 真正影响可维护性的不是“文档有没有”，而是打开
index.php时，能否3秒内看清bootstrap.php在哪、为什么必须先加载它
注释的本质不是凑行数，是降低下一个人（包括未来的你）理解路径意图的时间成本。最危险的情况是：注释写着“旧版兼容保留”，结果那文件早被删了，而require因为用了@抑制符，连报错都没有。
