头像

嘻道奇闻

  • 文章199742
  • 阅读14625734

热门文章

首页 > 社会 > 正文内容

PHP开发必看：文档注释规范与代码可读性提升指南

社会2025-05-27 18:31:13

??有没有遇到过这种情况？??
上周帮朋友看他的项目，打开文件直接懵圈——满屏的a、a、a、b、$tmp，函数名都是doSomething()，注释写着"这里很重要别乱改"。好家伙，这代码简直是密码本啊！今天咱就唠唠怎么用文档注释把这坨"密码"变成正常人能看懂的说明书。

一、文档注释可不是装逼用的

（啪！拍桌子声）我发现很多新手总把写注释当应付差事，这就大错特错了。去年接手个二手项目，那代码注释写的比埃及象形文字还抽象：

php复制
/**
 * 处理数据
 * @param $data 数据
 */
function process($data) {
    // 魔法发生在这里
}

结果光搞明白这个"魔法"是啥就花了两天——说白了就是个订单状态更新！

??正经文档注释三件套你得有??：

  1. ??功能说明书??：别说"处理数据"，要说"将未支付订单标记为超时取消"
  2. ??参数身份证??：类型、取值范围、特殊要求都得写明白
  3. ??返回值说明书??：是数组还是对象？有没有特殊数据结构？

二、手把手教你写人话注释

举个真实案例，上周实习生写的用户注册函数：

php复制
/**
 * 保存用户
 * @param $user 用户
 */
function save($user) {
    // 保存操作
}

改完之后是这画风：

php复制
/**
 * 创建新用户并初始化账户信息
 * @param array $user 必须包含['mobile','password']
 *   - mobile 要求11位数字且未注册
 *   - password 需预先经过sha256加密
 * @return int 新用户UID，失败返回0
 */
function createUser(array $user): int {
    // 这里藏了个彩蛋：自动发放新人优惠券
}

??重点来了??：当你在参数里写清楚规则，测试妹子能少找你八回！别问我怎么知道的...

三、这些坑我替你踩过了

有次在支付模块看到这样的注释：

php复制
// 重要！千万别动！会爆炸！

（扶额）大哥你倒是说清楚啊！后来发现就是个金额四舍五入的兼容处理。

??血泪换来的注释规范??：

  1. ??危险操作要亮红灯??： 
    php复制
    /**
 * @warning 修改此方法必须同步更新风控规则表
 */
  2. ??过期注释比没注释更可怕??： 
    php复制
    // 2018年双十一临时方案（已废弃）
// 现用方案见PaymentHandlerV2类
  3. ??团队暗号要统一??：
    • @todo 后面必须跟责任人名字
    • @deprecated 必须说明替代方案路径

四、你以为的常识可能是别人的知识盲区

上周有个妹子问我："为啥要写@param string $phone？变量名不是写着phone吗？" 问得我虎躯一震——对啊，有些事老手觉得理所当然，新手就是不知道啊！

??新人友好型注释要这么写??：

php复制
/**
 * 发送短信验证码
 * @param string $phone 手机号格式：11位数字，1开头
 * @param int $type 业务类型：
 *   1=注册 2=登录 3=改密（见const定义）
 * @throws Exception 超过当日发送次数会抛异常
 */

看这注释，连异常情况都交代了，这才是合格的代码说明书嘛！

五、文档注释的隐藏玩法

你知道PHPStorm能自动生成文档吗？按住Ctrl+鼠标点击函数名，选择"Generate PHPDoc"直接生成模板。不过自动生成的都是骨架，关键信息还得自己填。

??高阶技巧偷着乐??：

  1. 用@link直接关联JIRA任务： 
    php复制
    * @link https://jira.xxx.com/browse/PROJ-123
  2. 示例代码比文字好使： 
    php复制
    * @example
* $user = getUser(1024);
* echo $user['nickname'];
  3. 给维护者留小纸条： 
    php复制
    // 王哥，这部分跟订单结算耦合了
// 下次重构记得看《解耦方案.md》

六、真人真事告诉你注释多重要

上个月公司来了个新人，靠着完整的文档注释，三天就搞定了订单模块的需求开发。同期另一个项目组的小哥，因为注释写成"此处修改需谨慎"，改出个线上事故，凌晨三点被夺命连环call...

最近在Github看到个数据：有完整文档注释的开源项目，issue解决速度快了40%。你品，你细品。

??最后说点掏心窝子的??：
写注释就跟穿秋裤似的，当下觉得麻烦，事后直呼真香。记住啊，你今天写的不是注释，是三个月后自己看不懂代码时的救命符！前几天翻自己半年前写的代码，要不是注释写得详细，差点以为被外星人篡改了代码——真的，没注释的代码连自己都嫌弃！

相关推荐

搜索