进阶 yourls.org 2026-11-19 17:39:56 · 2 阅读

第2章 YOURLS 编码规范指南

编码规范 #1 要么遵守规则,要么出局 可读性比巧妙或简洁更重要。 向 master 分支上的最新开发版本提交补丁,而不是提交给最新发布的正式包。同时检查一下,你的功能或修复是否已在其他分支中被处理。 强制命名规范 命名使用小写字母和下划线(即 snake_case)。 示例: function yourls_check_php_version() {...} $valid_user = ... 不要使用 camelCase,例如 fetchSqlTableResult(抱歉,PSR2 规定如此)。 使用明确且自文档化的名称,避免使用通用且无意义的名字(如 function2() 或全局变量 $a) 在核心补丁中,所有 PHP 函数都必须加上 yourls_ 前缀。 在插件中,所有元素(函数、类、全局变量、HTML 元素等)都要加上唯一且个性化的前缀,例如 joe_myplugin_ 花括号与函数名在同一行 我们通常将花括号放在函数或类声明的同一行。 正确: function yourls_do_something( $string, $var ) { ... } 错误: function yourls_do_something( $string, $var ) { ... } 强制使用 4 空格缩进 缩进应反映代码的逻辑结构,且必须使用 4 个空格。 建议注释 注释宁多勿少。在提交补丁前删除几条注释,远比事后抓头发试图理解代码逻辑要好。 对于简单说明,使用行内注释。对于较长的说明,不要犹豫,使用 / ... */ 进行多行注释。 注释的重点不应是“做了什么”(除非代码本身不够自解释),而应是“为什么这么做”。 建议空格使用 代码必须反映逻辑结构,且视觉上舒适 在行首使用 4 个空格的块进行缩进 尽可能对齐元素,以提升可读性 垂直对齐行首代码块和行尾代码块,使其与开括号 ()、中括号 [ 和大括号 {} 对齐 在需要之处添加空格,让代码更有呼吸感 $value } { ... // 定义函数 function do_stuff( $param1= 'foo', $param2 = 'bar' ) { ... // 调用函数 do_stuff( '31337', other_func( 42 ) ); // 变量数组项周围加空格 $x = $foo['bar']; // 字符串,无空格可以 $y = $foo[ $bar ]; // 变量,需要加空格
// 如果垂直对齐能提高可读性
$this_var = 'hello';
$this_other = 'world';
$omg_lol = 'ozh';

PHP 标签​ 始终使用完整的 PHP 标签。 正确:
禁止:

另外,PHP 文件末尾的结束标签最好省略。 开启调试​ 开发时要始终开启错误报告。在 YOURLS 中,也就是要在开发用的 config.php 里加上: define( 'YOURLS_DEBUG', true );
不要硬编码 URL 或路径​ 用户可能把插件放在任意目录,不一定在 /user/plugins;可能重命名了你的插件目录;也可能用的是 https 而不是 http。 不要硬编码任何路径或 URL,有现成的函数可以用,比如 dirname()、yourls_plugin_url() 和 yourls_admin_url()。 不要硬编码输出的字符串​ 如果需要输出文字,不要直接硬编码英文,而应使用 Translation API。 错误做法: 正确做法: 更多信息请阅读语言使用指南,尤其是面向开发者的 i18n 说明。

评论 (0)