代碼風格指南

本手冊是基礎代碼規範(PSR-1)的繼承和擴展。

爲了儘可能的提升閱讀其他人代碼時的效率，下面例舉了一系列的通用規則，特別是有關於PHP代碼風格的。

各個成員項目間的共性組成了這組代碼規範。當開發者們在多個項目中合作時，本指南將會成爲所有這些項目中共用的一組代碼規範。因此，本指南的益處不在於這些規則本身，而在於在所有項目中共用這些規則。

RFC 2119中的必須(MUST)，不可(MUST NOT)，建議(SHOULD)，不建議(SHOULD NOT)，可以/可能(MAY)等關鍵詞將在本節用來做一些解釋性的描述。

1. 概述

代碼必須遵守 PSR-1。
代碼必須使用4個空格來進行縮進，而不是用製表符。
一行代碼的長度不建議有硬限制；軟限制必須爲120個字符，建議每行代碼80個字符或者更少。
在命名空間(namespace)的聲明下面必須有一行空行，並且在導入(use)的聲明下面也必須有一行空行。
類(class)的左花括號必須放到其聲明下面自成一行，右花括號則必須放到類主體下面自成一行。
方法(method)的左花括號必須放到其聲明下面自成一行，右花括號則必須放到方法主體的下一行。
所有的屬性(property)和方法(method) 必須有可見性聲明；抽象(abstract)和終結(final)聲明必須在可見性聲明之前；而靜態(static)聲明必須在可見性聲明之後。
在控制結構關鍵字的後面必須有一個空格；而方法(method)和函數(function)的關鍵字的後面不可有空格。
控制結構的左花括號必須跟其放在同一行，右花括號必須放在該控制結構代碼主體的下一行。
控制結構的左括號之後不可有空格，右括號之前也不可有空格。

1.1. 示例

這個示例中簡單展示了上文中提到的一些規則：

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{
    public function sampleFunction($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // 方法主體
    }
}

2. 通則

2.1 基礎代碼規範

代碼必須遵守 PSR-1 中的所有規則。

2.2 源文件

所有的PHP源文件必須使用Unix LF(換行)作爲行結束符。

所有PHP源文件必須以一個空行結束。

純PHP代碼源文件的關閉標籤?> 必須省略。

2.3. 行

行長度不可有硬限制。

行長度的軟限制必須是120個字符；對於軟限制，代碼風格檢查器必須警告但不可報錯。

一行代碼的長度不建議超過80個字符；較長的行建議拆分成多個不超過80個字符的子行。

在非空行後面不可有空格。

空行可以用來增強可讀性和區分相關代碼塊。

一行不可多於一個語句。

2.4. 縮進

代碼必須使用4個空格，且不可使用製表符來作爲縮進。

注意：代碼中只使用空格，且不和製表符混合使用，將會對避免代碼差異，補丁，歷史和註解中的一些問題有幫助。空格的使用還可以使通過調整細微的縮進來改進行間對齊變得更加的簡單。

2.5. 關鍵字和 True/False/Null

PHP關鍵字(keywords)必須使用小寫字母。

PHP常量true, false和null 必須使用小寫字母。

3. `命名空間(Namespace)`和`導入(Use)`聲明

命名空間(namespace)的聲明後面必須有一行空行。

所有的導入(use)聲明必須放在命名空間(namespace)聲明的下面。

一句聲明中，必須只有一個導入(use)關鍵字。

在導入(use)聲明代碼塊後面必須有一行空行。

示例：

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... 其它PHP代碼 ...

4. `類(class)`，`屬性(property)`和`方法(method)`

術語“類”指所有的類(class)，接口(interface)和特性(trait)。

4.1. `擴展(extend)`和`實現(implement)`

一個類的擴展(extend)和實現(implement)關鍵詞必須和類名(class name)在同一行。

類(class)的左花括號必須放在下面自成一行；右花括號必須放在類(class)主體的後面自成一行。

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // 常量、屬性、方法
}

實現(implement)列表可以被拆分爲多個縮進了一次的子行。如果要拆成多個子行，列表的第一項必須要放在下一行，並且每行必須只有一個接口(interface)。

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // 常量、屬性、方法
}

4.2. `屬性(property)`

所有的屬性(property)都必須聲明其可見性。

變量(var)關鍵字不可用來聲明一個屬性(property)。

一條語句不可聲明多個屬性(property)。

屬性名(property name) 不推薦用單個下劃線作爲前綴來表明其保護(protected)或私有(private)的可見性。

一個屬性(property)聲明看起來應該像下面這樣。

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

4.3. `方法(method)`

所有的方法(method)都必須聲明其可見性。

方法名(method name) 不推薦用單個下劃線作爲前綴來表明其保護(protected)或私有(private)的可見性。

方法名(method name)在其聲明後面不可有空格跟隨。其左花括號必須放在下面自成一行，且右花括號必須放在方法主體的下面自成一行。左括號後面不可有空格，且右括號前面也不可有空格。

一個方法(method)聲明看來應該像下面這樣。注意括號，逗號，空格和花括號的位置：

<?php
namespace Vendor\Package;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // 方法主體部分
    }
}

4.4. `方法(method)`的參數

在參數列表中，逗號之前不可有空格，而逗號之後則必須要有一個空格。

方法(method)中有默認值的參數必須放在參數列表的最後面。

<?php
namespace Vendor\Package;

class ClassName
{
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // 方法主體部分
    }
}

參數列表可以被拆分爲多個縮進了一次的子行。如果要拆分成多個子行，參數列表的第一項必須放在下一行，並且每行必須只有一個參數。

當參數列表被拆分成多個子行，右括號和左花括號之間必須又一個空格並且自成一行。

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // 方法主體部分
    }
}

4.5. `抽象(abstract)`，`終結(final)`和 `靜態(static)`

當用到抽象(abstract)和終結(final)來做類聲明時，它們必須放在可見性聲明的前面。

而當用到靜態(static)來做類聲明時，則必須放在可見性聲明的後面。

<?php
namespace Vendor\Package;

abstract class ClassName
{
    protected static $foo;

    abstract protected function zim();

    final public static function bar()
    {
        // 方法主體部分
    }
}

4.6. 調用方法和函數

調用一個方法或函數時，在方法名或者函數名和左括號之間不可有空格，左括號之後不可有空格，右括號之前也不可有空格。參數列表中，逗號之前不可有空格，逗號之後則必須有一個空格。

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);

參數列表可以被拆分成多個縮進了一次的子行。如果拆分成子行，列表中的第一項必須放在下一行，並且每一行必須只能有一個參數。

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

5. 控制結構

下面是對於控制結構代碼風格的概括：

控制結構的關鍵詞之後必須有一個空格。
控制結構的左括號之後不可有空格。
控制結構的右括號之前不可有空格。
控制結構的右括號和左花括號之間必須有一個空格。
控制結構的代碼主體必須進行一次縮進。
控制結構的右花括號必須主體的下一行。

每個控制結構的代碼主體必須被括在花括號裏。這樣可是使代碼看上去更加標準化，並且加入新代碼的時候還可以因此而減少引入錯誤的可能性。

5.1. `if`，`elseif`，`else`

下面是一個if條件控制結構的示例，注意其中括號，空格和花括號的位置。同時注意else和elseif要和前一個條件控制結構的右花括號在同一行。

<?php
if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}

推薦用elseif來替代else if，以保持所有的條件控制關鍵字看起來像是一個單詞。

5.2. `switch`，`case`

下面是一個switch條件控制結構的示例，注意其中括號，空格和花括號的位置。case語句必須要縮進一級，而break關鍵字（或其他中止關鍵字）必須和case結構的代碼主體在同一個縮進層級。如果一個有主體代碼的case結構故意的繼續向下執行則必須要有一個類似於// no break的註釋。

<?php
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循環控制結構的示例，注意其中括號，空格和花括號的位置。

<?php
while ($expr) {
    // structure body
}

下面是一個do while循環控制結構的示例，注意其中括號，空格和花括號的位置。

<?php
do {
    // structure body;
} while ($expr);

5.4. `for`

下面是一個for循環控制結構的示例，注意其中括號，空格和花括號的位置。

<?php
for ($i = 0; $i < 10; $i++) {
    // for body
}

5.5. `foreach`

下面是一個foreach循環控制結構的示例，注意其中括號，空格和花括號的位置。

<?php
foreach ($iterable as $key => $value) {
    // foreach body
}

5.6. `try`, `catch`

下面是一個try catch異常處理控制結構的示例，注意其中括號，空格和花括號的位置。

<?php
try {
    // try body
} catch (FirstExceptionType $e) {
    // catch body
} catch (OtherExceptionType $e) {
    // catch body
}

6. 閉包

聲明閉包時所用的function關鍵字之後必須要有一個空格，而use關鍵字的前後都要有一個空格。

閉包的左花括號必須跟其在同一行，而右花括號必須在閉包主體的下一行。

閉包的參數列表和變量列表的左括號後面不可有空格，右括號的前面也不可有空格。

閉包的參數列表和變量列表中逗號前面不可有空格，而逗號後面則必須有空格。

閉包的參數列表中帶默認值的參數必須放在參數列表的結尾部分。

下面是一個閉包的示例。注意括號，空格和花括號的位置。

<?php
$closureWithArgs = function ($arg1, $arg2) {
    // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

參數列表和變量列表可以被拆分成多個縮進了一級的子行。如果要拆分成多個子行，列表中的第一項必須放在下一行，並且每一行必須只放一個參數或變量。

當列表（不管是參數還是變量）最終被拆分成多個子行，右括號和左花括號之間必須要有一個空格並且自成一行。

下面是一個參數列表和變量列表被拆分成多個子行的示例。

<?php
$longArgs_noVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) {
   // body
};

$noArgs_longVars = function () use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // body
};

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // body
};

$longArgs_shortVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use ($var1) {
   // body
};

$shortArgs_longVars = function ($arg) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // body
};

把閉包作爲一個參數在函數或者方法中調用時，依然要遵守上述規則。

<?php
$foo->bar(
    $arg1,
    function ($arg2) use ($var1) {
        // body
    },
    $arg3
);

7. 結論

本指南有意的省略了許多元素的代碼風格。主要包括：

全局變量和全局常量的聲明
函數聲明
操作符和賦值
行間對齊
註釋和文檔塊
類名的前綴和後綴
最佳實踐

以後的代碼規範中可能會修正或擴展本指南中規定的代碼風格。

附錄A 調查

爲了寫這個風格指南，我們調查了各個項目以最終確定通用的代碼風格。並把這次調查在這裏公佈出來。

A.1. 調查數據

url,http://www.horde.org/apps/horde/docs/CODING_STANDARDS,http://pear.php.net/manual/en/standards.php,http://solarphp.com/manual/appendix-standards.style,http://framework.zend.com/manual/en/coding-standard.html,http://symfony.com/doc/2.0/contributing/code/standards.html,http://www.ppi.io/docs/coding-standards.html,https://github.com/ezsystems/ezp-next/wiki/codingstandards,http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html,https://github.com/UnionOfRAD/lithium/wiki/Spec%3A-Coding,http://drupal.org/coding-standards,http://code.google.com/p/sabredav/,http://area51.phpbb.com/docs/31x/coding-guidelines.html,https://docs.google.com/a/zikula.org/document/edit?authkey=CPCU0Us&hgd=1&id=1fcqb93Sn-hR9c0mkN6m_tyWnmEvoswKBtSc0tKkZmJA,http://www.chisimba.com,n/a,https://github.com/Respect/project-info/blob/master/coding-standards-sample.php,n/a,Object Calisthenics for PHP,http://doc.nette.org/en/coding-standard,http://flow3.typo3.org,https://github.com/propelorm/Propel2/wiki/Coding-Standards,http://developer.joomla.org/coding-standards.html
voting,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,no,no,no,?,yes,no,yes
indent_type,4,4,4,4,4,tab,4,tab,tab,2,4,tab,4,4,4,4,4,4,tab,tab,4,tab
line_length_limit_soft,75,75,75,75,no,85,120,120,80,80,80,no,100,80,80,?,?,120,80,120,no,150
line_length_limit_hard,85,85,85,85,no,no,no,no,100,?,no,no,no,100,100,?,120,120,no,no,no,no
class_names,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,lower_under,studly,lower,studly,studly,studly,studly,?,studly,studly,studly
class_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,next,next,next,next,next,next,same,next,next
constant_names,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper
true_false_null,lower,lower,lower,lower,lower,lower,lower,lower,lower,upper,lower,lower,lower,upper,lower,lower,lower,lower,lower,upper,lower,lower
method_names,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,lower_under,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel
method_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,same,next,next,next,next,next,same,next,next
control_brace_line,same,same,same,same,same,same,next,same,same,same,same,next,same,same,next,same,same,same,same,same,same,next
control_space_after,yes,yes,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes
always_use_control_braces,yes,yes,yes,yes,yes,yes,no,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes
else_elseif_line,same,same,same,same,same,same,next,same,same,next,same,next,same,next,next,same,same,same,same,same,same,next
case_break_indent_from_switch,0/1,0/1,0/1,1/2,1/2,1/2,1/2,1/1,1/1,1/2,1/2,1/1,1/2,1/2,1/2,1/2,1/2,1/2,0/1,1/1,1/2,1/2
function_space_after,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no
closing_php_tag_required,no,no,no,no,no,no,no,no,yes,no,no,no,no,yes,no,no,no,no,no,yes,no,no
line_endings,LF,LF,LF,LF,LF,LF,LF,LF,?,LF,?,LF,LF,LF,LF,?,,LF,?,LF,LF,LF
static_or_visibility_first,static,?,static,either,either,either,visibility,visibility,visibility,either,static,either,?,visibility,?,?,either,either,visibility,visibility,static,?
control_space_parens,no,no,no,no,no,no,yes,no,no,no,no,no,no,yes,?,no,no,no,no,no,no,no
blank_line_after_php,no,no,no,no,yes,no,no,no,no,yes,yes,no,no,yes,?,yes,yes,no,yes,no,yes,no
class_method_control_brace,next/next/same,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/next,same/same/same,same/same/same,same/same/same,same/same/same,next/next/next,next/next/same,next/same/same,next/next/next,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/same,next/next/next

A.2. 調查說明

indent_type:
縮進類型。 tab = “使用製表符”，2 or 4 = “空格數量”

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. 調查結果

indent_type:
    tab: 7
    2: 1
    4: 14
line_length_limit_soft:
    ?: 2
    no: 3
    75: 4
    80: 6
    85: 1
    100: 1
    120: 4
    150: 1
line_length_limit_hard:
    ?: 2
    no: 11
    85: 4
    100: 3
    120: 2
class_names:
    ?: 1
    lower: 1
    lower_under: 1
    studly: 19
class_brace_line:
    next: 16
    same: 6
constant_names:
    upper: 22
true_false_null:
    lower: 19
    upper: 3
method_names:
    camel: 21
    lower_under: 1
method_brace_line:
    next: 15
    same: 7
control_brace_line:
    next: 4
    same: 18
control_space_after:
    no: 2
    yes: 20
always_use_control_braces:
    no: 3
    yes: 19
else_elseif_line:
    next: 6
    same: 16
case_break_indent_from_switch:
    0/1: 4
    1/1: 4
    1/2: 14
function_space_after:
    no: 22
closing_php_tag_required:
    no: 19
    yes: 3
line_endings:
    ?: 5
    LF: 17
static_or_visibility_first:
    ?: 5
    either: 7
    static: 4
    visibility: 6
control_space_parens:
    ?: 1
    no: 19
    yes: 2
blank_line_after_php:
    ?: 1
    no: 13
    yes: 8
class_method_control_brace:
    next/next/next: 4
    next/next/same: 11
    next/same/same: 1
    same/same/same: 6

PSR-2-coding-style-guide

代碼風格指南

1. 概述

1.1. 示例

2. 通則

2.1 基礎代碼規範

2.2 源文件

2.3. 行

2.4. 縮進

2.5. 關鍵字和 True/False/Null

3. `命名空間(Namespace)`和`導入(Use)`聲明

4. `類(class)`，`屬性(property)`和`方法(method)`

4.1. `擴展(extend)`和`實現(implement)`

4.2. `屬性(property)`

4.3. `方法(method)`

4.4. `方法(method)`的參數

4.5. `抽象(abstract)`，`終結(final)`和 `靜態(static)`

4.6. 調用方法和函數

5. 控制結構

5.1. `if`，`elseif`，`else`

5.2. `switch`，`case`

5.3. `while`，`do while`

5.4. `for`

5.5. `foreach`

5.6. `try`, `catch`

6. 閉包

7. 結論

附錄A 調查

A.1. 調查數據

A.2. 調查說明

A.3. 調查結果

微服務實踐之使用 Visual Studio 2022 調試Dapr 應用程序

wpf附加屬性理解 WPF附加屬性

MacOS--通過homebrew下載過慢問題

PSR-3-logger-interface

PSR-2-coding-style-guide

PSR-4-autoloader

PSR-1-basic-coding-standard

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

PSR-2-coding-style-guide

代碼風格指南

1. 概述

1.1. 示例

2. 通則

2.1 基礎代碼規範

2.2 源文件

2.3. 行

2.4. 縮進

2.5. 關鍵字和 True/False/Null

3. 命名空間(Namespace)和導入(Use)聲明

4. 類(class)，屬性(property)和方法(method)

4.1. 擴展(extend)和實現(implement)

4.2. 屬性(property)

4.3. 方法(method)

4.4. 方法(method)的參數

4.5. 抽象(abstract)，終結(final)和 靜態(static)

4.6. 調用方法和函數

5. 控制結構

5.1. if，elseif，else

5.2. switch，case

5.3. while，do while

5.4. for

5.5. foreach

5.6. try, catch

6. 閉包

7. 結論

附錄A 調查

A.1. 調查數據

A.2. 調查說明

A.3. 調查結果

3. `命名空間(Namespace)`和`導入(Use)`聲明

4. `類(class)`，`屬性(property)`和`方法(method)`

4.1. `擴展(extend)`和`實現(implement)`

4.2. `屬性(property)`

4.3. `方法(method)`

4.4. `方法(method)`的參數

4.5. `抽象(abstract)`，`終結(final)`和 `靜態(static)`

5.1. `if`，`elseif`，`else`

5.2. `switch`，`case`

5.3. `while`，`do while`

5.4. `for`

5.5. `foreach`

5.6. `try`, `catch`