WordPress:WordPress Coding Standards

Some legacy parts of the WordPress code structure for PHP markup are inconsistent in their style. WordPress is working to gradually improve this by helping users maintain a consistent style so the code can remain clean and easy to read at a glance.

一些WordPress代碼結(jié)構(gòu)遺留下來的部分對于PHP的發(fā)展在類型上是不一致的。 WordPress致力于通過幫助用戶維護(hù)代碼一致性，維持整潔易讀的程度來逐漸改變這點(diǎn)。

Keep the following points in mind when writing code for WordPress, whether for core programming code, Plugins, or WordPress Themes. The guidelines are similar to Pear standards in many ways, but differ in some key respects.

編寫WordPress 代碼的時(shí)候，要記得以下幾點(diǎn)，不論是核心程序代碼， 插件，或者是 WordPress 主題。指導(dǎo)方針與 Pear 標(biāo)準(zhǔn)相似，但是在某些關(guān)鍵地方也有不同。

Also see this post on the wp-hackers list.

也可以參見wp-hackers 列表中的這個(gè)文章

There is also a page on proposed WordPress:Inline Documentation standards.

Single and double quotes

Use single and double quotes when appropriate. If you're not evaluating anything in the string, use single quotes. You should almost never have to escape HTML quotes in a string, because you can just alternate your quoting style, like so:

echo "<a href='$link' title='$linktitle'>$linkname</a>";
echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';

還有一篇關(guān)于被提議的內(nèi)嵌文檔標(biāo)準(zhǔn)的頁面.

單引號(hào)和雙引號(hào)

適當(dāng)?shù)臅r(shí)候使用單引號(hào)和雙引號(hào)。如果你不能評測字符串中的東西的時(shí)候，使用單引號(hào)。字符串無法擺脫HTML 引號(hào)，因?yàn)槟阒豢梢愿淖兡愕囊梅绞?，?

echo "<a href='$link' title='$linktitle'>$linkname</a>";
echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';

The only exception to this is JavaScript, which sometimes requires double or single quotes. Text that goes into attributes should be run through attribute_escape() so that single or double quotes do not end the attribute value and invalidate the XHTML and cause a security issue.

Indentation

Your indentation should always reflect logical structure. Use real tabs and not spaces, as this allows the most flexibility across clients.

唯一的例外是JavaScript，它有時(shí)要求雙或者單引號(hào)。屬性中的文本必須通過attribute_escape()處理，這樣單或者雙引號(hào)不需要結(jié)束屬性的值，也不會(huì)導(dǎo)致XHTML 不合法而導(dǎo)致安全問題。

縮進(jìn)

縮進(jìn)通常反映出邏輯結(jié)構(gòu)。使用真正的制表符 而不要使用空格，這通過客戶端允許得到最大的適應(yīng)性。

Exception: if you have a block of code that would be more readable if things aligned, you can do initial indentation with tabs and then make up the difference with spaces:

[tab]$foo   = 'somevalue';
[tab]$foo2  = 'somevalue2';
[tab]$foo34 = 'somevalue3';
[tab]$foo5  = 'somevalue4';

例外: 如果代碼排列整齊了會(huì)使你的代碼塊更易讀的話，你可以做一些簡單的制表符縮進(jìn)，然后把不同的地方用空格標(biāo)記：

[tab]$foo   = 'somevalue';
[tab]$foo2  = 'somevalue2';
[tab]$foo34 = 'somevalue3';
[tab]$foo5  = 'somevalue4';

Note how tabs are used for the initial indentation, and spaces are just used to make sure the equals signs line up.

Brace Style

Braces should be used for multiline blocks:

if ( condition ) {
    action1();
    action2();
} elseif ( condition2 && condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
}

注意制表符如何用來做簡單的縮進(jìn)，和空格只是用來讓每行排列整齊。

Brace 格式

Brace應(yīng)該用于多行代碼塊:

if ( condition ) {
    action1();
    action2();
} elseif ( condition2 && condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
}

Furthermore if you have a really long block, consider if it can be broken into two or more shorter blocks or function. If you consider such a long block unavoidable, please put a short comment at the end so people can tell at glance what that ending brace ends -- typically this is appropriate for a logic block, longer than about 35 rows, but any code that's not intuitively obvious can be commented.

此外如果你有特別長的代碼塊，考慮是否可以分成兩個(gè)或者更多的短些的塊或者函數(shù)。如果你認(rèn)為這種長代碼不可避免，請?jiān)谀┪沧鲆粋€(gè)簡單的注釋，這樣人們可以在看過之后知道結(jié)束括號(hào)結(jié)束了什么。 -- 尤其是適合邏輯塊，超過35行的代碼，當(dāng)然任何代碼都是可以做出注釋的。

single line blocks can omit braces for brevity:

if ( condition )
    action1();
elseif ( condition2 )
    action2();
else
    action3();

單行程序塊可以省略大括號(hào):

if ( condition )
    action1();
elseif ( condition2 )
    action2();
else
    action3();

include_once vs. require_once

Learn the difference between include_once and require_once, and use each as appropriate. To quote the php manual page on include(): "The two constructs are identical in every way except how they handle failure. include() produces a Warning while require() results in a Fatal Error." Fatal errors stop script execution.

include_once vs. require_once

了解 include_once 和 require_once之間的不同，適當(dāng)?shù)氖褂盟鼈?。引?a target="_blank" rel="nofollow noreferrer noopener" class="external autonumber" 這兩種結(jié)構(gòu)除了在如何處理故障方面，其他的都是一樣的。當(dāng)require() 導(dǎo)致一個(gè)致命錯(cuò)誤的時(shí)候，include() 生成一個(gè)警告。" 致命錯(cuò)誤停止代碼執(zhí)行。

Regular expressions

Perl compatible regular expressions (PCRE, preg_ functions) should be used in preference to their POSIX counterparts.

No Shorthand PHP

Never use shorthand PHP start tags (<? ... ?> or <?=$var?>). Always use full PHP tags (<?php ... ?>). Make sure to remove trailing whitespace after closing PHP tag.

常規(guī)表達(dá)

Perl 兼容常規(guī)表達(dá)(PCRE, preg_ 函數(shù))應(yīng)該被優(yōu)先用在 它們的POSIX 副本.

不要使用簡寫PHP

不要使用簡寫PHP 開始標(biāo)簽 (<? ... ?> 或者 <?=$var?>)。要一直使用完全的PHP 標(biāo)簽 (<?php ... ?>). 確認(rèn)關(guān)閉PHP標(biāo)簽后移除空白空格。

Space Usage

Always put spaces after commas and on both sides of logical and assignment operators like "x == 23", "foo && bar", "array( 1, 2, 3 )", , as well as on both sides of the opening and closing parenthesis of if, elseif, foreach, for and switch blocks (e.g. foreach ( $foo as $bar ) { ...). When defining a function, do it like so: function myfunction( $param1 = 'foo', $param2 = 'bar' ) { and when calling a function, do it like so: myfunction( $param1, funcparam( $param2 ) );

空格用法

在逗號(hào)后面要加一個(gè)空格，在邏輯和分配算子兩邊也要加上空格如 "x == 23", "foo && bar", "array( 1, 2, 3 )", , 同樣在打開和關(guān)閉if, elseif, foreach, for 和 switch 語句的括號(hào)兩邊也加上空格 (如foreach ( $foo as $bar ) { ...). 定義一個(gè)函數(shù)的時(shí)候，這樣做: function myfunction( $param1 = 'foo', $param2 = 'bar' ) { 在調(diào)用函數(shù)的時(shí)候，這樣做: myfunction( $param1, funcparam( $param2 ) );

Formatting SQL statements

When formatting SQL statements you may break it into several lines and indent if it is sufficiently complex to warrant it. Most statements work well as one line though. Always capitalize the SQL parts of the statement like UPDATE or WHERE.

格式化 SQL 聲明

如果十分復(fù)雜而不能辨別的話，當(dāng)格式化SQL聲明的時(shí)候你可以把它分成幾行，然后縮進(jìn)。多數(shù)聲明在一行內(nèi)運(yùn)行良好。聲明的SQL部分如UPDATE 或者 WHERE一定要大寫。

Functions that update the database should expect their parameters to lack SQL slash escaping when passed. Escaping should be done as close to the time of the query as possible, preferably by using $wpdb->prepare()

升級(jí)數(shù)據(jù)庫的函數(shù)盡量減少參數(shù)應(yīng)該盼望參數(shù)在傳遞過程中減少丟失。溢出應(yīng)該在盡可能接近請求的時(shí)候完成。最適合的時(shí)候是正在使用 $wpdb->prepare()時(shí)。

$wpdb->prepare() is a method that handles escaping, quoting, and int-casting for SQL queries. It uses a subset of the sprintf() style of formatting. Example :

$var = "dangerous'"; // raw data that may or may not need to be escaped
$id  = some_foo_number(); // data we expect to be an integer, but we're not certain

$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );

$wpdb->prepare()是一個(gè)方法，為SQL請求控制溢出，引用和int-casting。它使用一個(gè)格式化的sprintf()格式的的子集。如 :

$var = "dangerous'"; // raw data that may or may not need to be escaped
$id  = some_foo_number(); // data we expect to be an integer, but we're not certain

$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );

%s is used for string placeholders and %d is used for integer placeholders. Note that they are not 'quoted'! $wpdb->prepare() will take care of escaping and quoting for us. The benefit of this is that we don't have to remember to manually use $wpdb->escape(), and also that it is easy to see at a glance whether something has been escaped or not, because it happens right when the query happens.

%s 是用于字符串占位符的，%d是用于整型占位符。注意它們沒有被'引用'! $wpdb->prepare()會(huì)照應(yīng)好溢出和引用的。這樣的好處就是我們不需要記住手動(dòng)使用$wpdb->escape()，這樣一眼就能看出是否有什么溢出，因?yàn)樗谡埱蟀l(fā)生的那一刻就起作用了。

Database Queries

Avoid touching the database directly. If there is a defined function that can get the data you need, use it. Database abstraction (using functions instead of queries) helps keep your code forward-compatible and, in cases where results are cached in memory, it can be many times faster. If you must touch the database, get in touch with some developers by posting a message to the wp-hackers mailing list. They may want to consider creating a function for the next WordPress version to cover the functionality you wanted.

數(shù)據(jù)庫請求

避免直接改動(dòng)數(shù)據(jù)庫。如果有一個(gè)定義過的函數(shù)可以得到你想要的數(shù)據(jù)，就用它，數(shù)據(jù)庫提取(使用函數(shù)代替請求)對保證你的代碼的向前兼容性有幫助，這樣結(jié)果在內(nèi)存中找到后，它可以用數(shù)倍更快的速度。如果你必須改動(dòng)數(shù)據(jù)庫的話，通過發(fā)布信息到wp-hackers 郵件列表聯(lián)系幾個(gè)開發(fā)人員。他們可能會(huì)考慮為下一個(gè)WordPress 版本開發(fā)一個(gè)新的函數(shù)來達(dá)到你想要的功能。

Variables, functions, and operators

If you don't use a variable more than once, don't create it. This includes queries. Always use the wpdb Class of functions when interacting with the database.

變量, 函數(shù)和算子

如果你不使用變量，就不要?jiǎng)?chuàng)建。這包括請求在內(nèi)。于數(shù)據(jù)庫交換數(shù)據(jù)時(shí)使用函數(shù)wpdb類。

Ternary operators are fine, but always have them test if the statement is true, not false. Otherwise it just gets confusing.

// GOOD example:
// (if statement is true) ? (do this) : (if false, do this);
$musictype = ('jazz' == $music) ? 'cool' : 'blah';

三重算子是可以的，聲明為真時(shí)要記得測試，否則它會(huì)混淆。

// GOOD example:
// (if statement is true) ? (do this) : (if false, do this);
$musictype = ('jazz' == $music) ? 'cool' : 'blah';

Another important point in the above example, when doing logical comparisons always put the variable on the right side, like above. If you forget an equal sign it'll throw a parse error instead of just evaluating true and executing the statement. It really takes no extra time to do, so if this saves one bug it's worth it.

另外一個(gè)重點(diǎn)是在上邊的例子中，當(dāng)做邏輯比較的時(shí)候，要把變量放到右邊，象上邊那樣。如果你忘記了等號(hào)，它會(huì)出現(xiàn)一個(gè)解析錯(cuò)誤而不是判斷為真或者停止聲明。它并不占用過多的時(shí)間，所以這如果避免了一個(gè)錯(cuò)誤，是值得的。