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