1. 【强制】类、类属性、类方法的注释必须/** 内容 */格式，不得使用// xxx 方式 说明：在各种IDE中，可以设置各种文件模板，类注释模板，方法注释模板，可以提前设置一下，在书写类，方法，函数的时候，会悬浮提示，点击后自动生成各种注释 正例 ``` /** * 行为管理控制器 * @package app\admin\controller */ class Action extends Base { /** * 首页 * @author 似水星辰 [ 2630481389@qq.com ] */ public function index() { ... } } ``` 2. 【强制】所有注释必须包含中文介绍，也就是说这个类或者方法，是干什么的； 3. 【强制】如果方法传递了参数，则要把每个参数的类型，以及参数的中文介绍写上； 4. 【强制】方法必须带返回类型，和作者，如果是非作者本人修改完善的，也要写上； 5. 【强制】单行注释可以使用 //， // 与注释内容之间有且仅有一个空格，如果 // 前面有非空字符，则 // 前面需要加一个空格，多行注释使用/* */注释，注意与代码对齐； 6. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改 说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。 7. 【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除 说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。 8. 【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作； 9. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担； ## 本规范示例 /** * 编辑行为 * @param int $id 行为id * @author 似水星辰 [ 2630481389@qq.com ] * @created 2019.03.29 * @return mixed */ public function edit($id = 0) { // 先判断id是否有效再进行其他操作 if ($id === 0) { $this->error('缺少参数'); } // 保存数据 if ($this->request->isPost()) { ... } } 注：本规范示例可参照代码格式范例