PHP的PSR规范中文版
|
文档仓库地址：https://github.com/hfcorriez/fig-standards PSR规范中文版
为何规范摘录翻译了官方的一句话 本组织旨在通过讨论我们代码项目的共同点以找出一个协作编程的方法。 在此想到了一篇文章《Google为何要执行严格的代码规范》中有这么一段话： 代码如下: 在谷歌，我可以查看任何的代码，进入所有谷歌的代码库，我有权查看它们。事实上，这种权限是很少人能拥有的。但是，让我感到惊讶的却是，如此多的编码规范—缩进，命名，文件结构，注释风格—这一切让我出乎意料的轻松的阅读任意一段代码，并轻易的看懂它们。这让我震惊—因为我以为这些规范是微不足道的东西。它们不可能有这么大的作用—但它们却起到了这么大的作用。当你发现只通过看程序的基本语法结构就能读懂一段代码，这种时间上的节省不能不让人震撼！ 各位看官我就不用多说关于规范的事情了。 写在最后 规范不是义务的，当然你也可以选择自己的方式，但使用规范会让你的合作更轻松。如今各种更现代化应用的编写已不像从前，一个应用一般都有非常多的模块组成，如果不执行规范，只会让整个项目的理解和沟通更加复杂。 若使用了规范，对项目和自己的好处当然不言而喻的。所有已接受的规范参考：https://github.com/hfcorriez/fig-standards/tree/zh_CN/%E6%8E%A5%E5%8F%97 代码样式规范本指南的意图是为了减少不同开发者在浏览代码时减少认知的差异。 为此列举一组如何格式化PHP代码的共用规则。各个成员项目的共性组成了本文的样式规则。当不同的开发者在不同的项目中合作时，将会在这些不同的项目中使用一个共同的标准。 因此，本指南的好处不在于规则本身，而在于共用这些规则。 在 RFC 2119中的特性关键词"必须"(MUST)，“不可”(MUST NOT)，“必要”(REQUIRED)，“将会”(SHALL)，“不会”(SHALL NOT)，“应当”(SHOULD)，“不应”(SHOULD NOT)，“推荐”(RECOMMENDED)，“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 1. 大纲代码必须遵守 PSR-1。 代码必须使用4个空格的缩进，而不是制表符。一行代码长度不应硬性限制；软限制必须为120个字符；也应当是80个字符或者更少。 在namespace声明下面必须有一个空行，并且use声明代码块下面也必须有一个空行。 类的左花括号必须放到下一行，右花括号必须放在类主体的下一行。 方法的左花括号必须放在下一行，右花括号必须放在方法主体下面。 所有的属性和方法必须有可见性(译者注：Public,Protect,Private)声明；abstract和final声明必须在可见性之前；static声明必须在可见性之后。 控制结构的关键词必须在后面有一个空格； 方法和函数不可有。 控制结构的左花括号必须放在同一行，右花括号必须放在控制主体的下一行。 控制结构的左括号后面不可有空格，右括号之前不可有空格。 1.1. 示例 代码如下: namespace VendorPackage;
use FooInterface; use BarClass as Bar; use OtherVendorOtherPackageBazClass; class Foo extends Bar implements FooInterface final public static function bar() 2. 概括 2.2 文件 所有PHP文件必须以一个空行结束。 纯PHP代码的文件关闭标签?>必须省略 2.3. 行 行长度的软限制必须是120个字符；对于软限制，自动样式检查器必须警告但不可报错。 行实际长度不应超过80个字符；较长的行应当被拆分成多个不超过80个字符的后续行。 在非空行后面不可有空格。 空行可以用来改善可读性和区分相关的代码块。 一行不应多于一个语句。 2.4. 缩进 注意：只用空格，不和制表符混合使用，将会对避免代码差异，补丁，历史和注解中的一些问题有帮助。使用空格还可以使调整细微的缩进来改进行间对齐变得非常简单。 2.5. 关键词和 True/False/Null PHP常量true,false和null必须使用小写。 3. Namespace和Use声明 如果存在，所有的use声明必须放在namespace声明的下面。 一个use关键字必须只用于一个声明。 在use声明代码块后面必须有一个空行。 示例: 代码如下: namespace VendorPackage;
use FooClass; // ... additional PHP code ... 4. 类，属性和方法 4.1. 扩展和继承 类的左花括号必须放在下面自成一行；右花括号必须放在类主体的后面自成一行。 代码如下: namespace VendorPackage;
use FooClass; use BarClass as Bar; use OtherVendorOtherPackageBazClass; class ClassName extends ParentClass implements ArrayAccess,Countable implements一个列表可以被拆分为多个有一次缩进的后续行。如果这么做，列表的第一项必须要放在下一行，并且每行必须只有一个接口。 代码如下: namespace VendorPackage;
use FooClass; class ClassName extends ParentClass implements 4.2. 属性 var关键词不可用来声明属性。 一个语句不可声明多个属性。 属性名称不应使用单个下划线作为前缀来表明保护或私有的可见性。 一个属性声明看起来应该下面这样的。 代码如下: namespace VendorPackage;
class ClassName 4.3. 方法 方法名不应只使用单个下划线来表明是保护或私有的可见性。 方法名在声明之后不可跟随一个空格。左花括号必须放在下面自成一行，并且右花括号必须放在方法主体的下面自成一行。左括号后面不可有空格，右括号前面不可有空格。 一个方法定义看来应该像下面这样。 注意括号，逗号，空格和花括号： 代码如下: namespace VendorPackage;
class ClassName 4.4. 方法参数 方法中有默认值的参数必须放在参数列表的最后面。 代码如下: namespace VendorPackage;
class ClassName 参数列表可以被分为多个有一次缩进的多个后续行。如果这么做，列表的第一项必须放在下一行，并且每行必须只放一个参数。 当参数列表被分为多行，右括号和左花括号必须夹带一个空格放在一起自成一行。 代码如下: namespace VendorPackage;
class ClassName 4.5. abstract，final和 static 如果存在，static声明必须跟着可见性声明。 代码如下: namespace VendorPackage;
abstract class ClassName abstract protected function zim(); final public static function bar() 4.6. 调用方法和函数 bar(); 代码如下: $foo->bar(
$longArgument, $longerArgument, $muchLongerArgument ); 5. 控制结构 控制结构关键词之后必须有一个空格 5.1. if，elseif，else 一个if结构看起来应该像下面这样。注意括号，空格，花括号的位置；并且else和elseif和前一个主体的右花括号在同一行。 代码如下: if ($expr1) {
// if body } elseif ($expr2) { // elseif body } else { // else body; } 关键词elseif应该替代else if使用以保持所有的控制关键词像一个单词。 5.2. switch，case 一个switch结构看起来应该像下面这样。注意括号，空格和花括号。case语句必须从switch处缩进，并且break关键字（或其他中止关键字）必须和case主体缩进在同级。如果一个非空的case主体往下落空则必须有一个类似// no break的注释。 代码如下: switch ($expr) { case 0: echo 'First case,with a break'; break; case 1: echo 'Second case,which falls through'; // no break case 2: case 3: case 4: echo 'Third case,return instead of break'; return; default: echo 'Default case'; break; } 5.3. while，do while 一个while语句看起来应该像下面这样。注意括号，空格和花括号的位置。 代码如下: while ($expr) { // structure body } 同样的，一个do while语句看起来应该像下面这样。注意括号，空格和花括号的位置。 代码如下: do {
// structure body; } while ($expr); 5.4. for 代码如下: for ($i = 0; $i < 10; $i++) {
// for body } 5.5. foreach 一个foreach语句看起来应该像下面这样。注意括号，空格和花括号的位置。 代码如下: foreach ($iterable as $key => $value) { // foreach body } 5.6. try,catch 一个try catch语句看起来应该像下面这样。注意括号，空格和花括号的位置。 代码如下: try {
// try body } catch (FirstExceptionType $e) { // catch body } catch (OtherExceptionType $e) { // catch body } 6. 闭包 闭包在声明时function关键词之后必须有一个空格，并且use之前也需要一个空格。 左花括号必须在同一行，右花括号必须在主体的下一行。 参数列表和变量列表的左括号之后不可有空格，其右括号之前也不可有空格。 在参数列表和变量列表中，逗号之前不可有空格，逗号之后必须有空格。 闭包带默认值的参数必须放在参数列表后面。 一个闭包声明看起来应该像下面这样。注意括号，空格和花括号的位置。 代码如下: $closureWithArgs = function ($arg1,$arg2) {
// body }; $closureWithArgsAndVars = function ($arg1,$arg2) use ($var1,$var2) { // body }; 参数和变量列表可以被分成多个带一次缩进的后续行。如果这么做，列表的第一项必须放在下一行，并且一行必须只放一个参数或变量。 当最终列表（不管是参数还是变量）被分成多行，右括号和左花括号必须夹带一个空格放在一起自成一行。 下面是一个参数和变量列表被分割成多行的示例。 代码如下: $longArgs_noVars = function ( $longArgument, $muchLongerArgument ) { // body }; $noArgs_longVars = function () use ( $longArgs_longVars = function ( $longArgs_shortVars = function ( $shortArgs_longVars = function ($arg) use ( 注意如果在函数或者方法中把闭包作为一个参数调用，如上格式规则同样适用。 代码如下: $foo->bar(
$arg1, function ($arg2) use ($var1) { // body }, $arg3 ); 7. 结论 全局变量和全局常量的声明 方法声明 操作符和赋值 行间对齐 注释和文档块 类名给你前缀和后缀 最佳实践 以后的建议可以修改和扩展该指南以满足这些或其他风格的元素和实践。 附录A 调查 A.1. 调查数据 line_length_limit_soft: 行长度的“软”限制，用字符。 ? = 不表示或者数字 no 意为不限制. line_length_limit_hard: 行长度的"硬"限制，用字符。 ? = 不表示或者数字,no 意为不限制. class_names: 类名如何命名 lower = 只是小写,lower_under = 小写加下划线,studly = 骆驼型. class_brace_line: 类的左花括号是放在同(same)一行还是在下(next)一行？ constant_names: 类常量如何命名？upper = 大写加下划线分隔符。 true_false_null: 全校写或者全大写？ method_names: 方法名如何命名？camel = 驼峰式,lower_under = 小写加下划线分隔符。 method_brace_line: 方法的左花括号在同(same)一行还是在下(next)一行？ control_brace_line: 控制结构的左花括号在同(same)一行还是在下(next)一行？ control_space_after: 控制结构关键词后是否有空格？ always_use_control_braces: 控制结构总是使用花括号？ else_elseif_line: 当使用else和elseif，是否放在同(same)一行还是在下(next)一行？ case_break_indent_from_switch: case和break分别从swith语句处缩进多少次？ function_space_after: 函数调用的函数名和左括号是否有空格？ closing_php_tag_required: 如过是纯PHP文件，关闭标签?>是否需要？ line_endings: 使用何种的行结束符？ static_or_visibility_first: 在定义方法的时候static和可见性谁在前面？ control_space_parens: 在控制结构表达式中，左括号后面和右括号前面是否要有一个空格？yes = if ( $expr ),no =if ($expr). blank_line_after_php: PHP的开始标签后面是否需要一个空行？ class_method_control_brace: 左花括号在类，方法和控制结构中的位置。 A.3. 调查结果 （编辑：李大同） 【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容! |