附：PHP底層編碼規則 · PHP底層內核源碼與擴展開發

--- --- # **譯文::** --- --- # PHP 源碼編碼標準翻譯任何想要添加或更改PHP源碼的開發者都應該遵循這個文檔下面列出的幾個標準。此文件從PHP v3.0版本的開發末期階段被添加,PHP的代碼還沒有完全遵循下面的標準, 但是會一直朝著這方向發展, 現在PHP5已經發布了, 大部分已經遵循了下面的規則 --- ## 代碼實現規則 1. **在源文件和技術手冊中對你的代碼做好描述** 2. **函數不應該釋放傳入的指針資源** 例如 `function int mail(char *to, char *from)` 不應該釋放參數 to 或 from . 除了以下情況: * 函數本身被設計為釋放資源例如 efree() . * 給定的函數參數包含一個布爾值, 這個參數被用來控制是否釋放,如果為真則函數釋放參數, 如果為假則不釋放 . * 與底層解析器程序緊密集成的令牌緩存或內存拷貝開銷最小的語法分析器生成器(GNU bison)代碼,(可以理解為C語言內嵌的一些匯編代碼) . 3. **在同一個模塊(module)中和其它函數耦合和彼此依賴的函數，應做好注釋并用static聲明。最好避免有這種情況** 4. **盡量使用definitions和macros，使常量有一個有意義的名字方便操作。除了0和1分別被當作false, true時可以例外,所有其它使用數值常量指定不同行為的情況都應該使用#define** 5. **當編寫和字符串處理相關的函數時,要知道PHP會記住每個字符串的長度屬性(使用zend_parse_parameters_ex獲取到的字符串長度),不要用strlen來計算它的長度(如果不是\0結尾的字符串strlen的計算是不準確的) .** 這樣編寫的函數能充分利用長度屬性，對效率和二進制安全都有好處。使用函數改變字符串并獲得他們的新長度的同時,應該返回新的長度,這樣就不用strlen重新計算了(例如 php_addslashes()) . 6. **絕對不要使用 strncat()函數. 如果你確定知道你在做什么. 請再三查看該函數的使用手冊, 想清楚再使用. 即使這樣也請盡量避免使用.** 7. **在PHP的源碼部分使用宏 PHP_* , 在Zend引擎源碼部分使用宏 ZEND_*** 盡管幾乎所有的宏 PHP_* 只是宏 ZEND_* 的一個別名. 但是它可以使代碼的閱讀性更好, 更容易理解你調用的是哪種宏 . 8. **當注釋掉一段代碼的時候不要只使用 #if 0 來聲明.** 用git的賬號加上_0 來代替, 例如 #if FOO_0, FOO表示你的git賬號. 這使得更容易跟蹤代碼被注釋掉了的原因, 尤其是在捆綁庫的時候. 9. **不要定義不可用的函數** 例如一個庫缺少一個函數或者這個函數沒有定義響應的PHP版本 . 如果在使用方法的時候也沒有報出方法不存在的運行時錯誤 , 用戶需要使用 function_exists() 去測試這個方法是否存在 . 10. **emalloc(), efree(), estrdup() 等函數是對標準C庫的一個封裝.** 這些方法實現了一個內部安全的機制,以確保回收沒有被釋放的內存 , 而且這些函數在debug模式下還提供了非常有用的分配和溢出的信息 . 在絕大多數情況下, 引擎中使用的內存必須使用 emalloc()函數來分配 . 只有在有限情況下才可能需要用malloc()等C庫函數來控制或釋放內存比如使用第三方庫 , 或者當這塊內存的生命周期需要在多個請求中生存的時候 . --- ## 用戶函數/方法名編碼規則約定 1. **用戶級函數的函數名應該用封閉的PHP_FUNCTION()宏** 函數名應該是小寫的,用字母和下劃線組合,盡量縮短函數名 ,但也不要用縮寫,會降低函數名本身的的可讀性 : ```code Good: 'mcrypt_enc_self_test' 'mysql_list_fields' Ok: 'mcrypt_module_get_algo_supported_key_sizes' (could be 'mcrypt_mod_get_algo_sup_key_sizes'?) 'get_html_translation_table' (could be 'html_get_trans_table'?) Bad: 'hw_GetObjectByQueryCollObj' 'pg_setclientencoding' 'jf_n_s_i' ``` 2. **如果函數是父集的一部分, 父集名稱應該包含在這個函數名中** 并且應該明確該函數在父集中的關聯性, 應該用 parent_* 形式來命名 , 例如和foo相關的一組函數集 : ```code Good: 'foo_select_bar' 'foo_insert_baz' 'foo_delete_baz' Bad: 'fooselect_bar' 'fooinsertbaz' 'delete_foo_baz' ``` 3. **功能型內部使用的函數名應該加前綴_php_** 緊隨其后的應該是一個單詞或用下劃線分割的一組詞, 并用小寫字母描述這個方法 . 如果可以的話, 這里盡量加static關鍵字 [這條可以去參考PHP源碼里的_php_stream_write_buffer函數] . 4. **變量名必須是有意義的. 避免使用一個字母的變量名** 除非這個變量名沒有實際意義或微不足道的意義. 例如for循環中的i . 5. **變量名應該用小寫字母. 詞與詞之間用下劃線分割** 6. **方法名如'studlyCaps'(可參考駝峰命名法) 命名約定.** 盡量簡化名字的字母個數,開頭的字母名字是小寫的并且名字新詞的首字母是大寫的 : ```code Good: 'connect()' 'getData()' 'buildSomeWidget()' Bad: 'get_Data()' 'buildsomewidget' 'getI()' ``` 7. **類應該給出描述性的名稱. 盡可能避免使用縮寫.** 每個詞的類名應該用大寫字母開始. 沒有下劃線分隔符(CamelCaps從一個大寫字母開始) , 類名應該有"父集"的名稱前綴(例如擴展的名稱[可參考PDO的命名規則]) : ```code Good: 'Curl' 'FooBar' Bad: 'foobar' 'foo_bar' ``` --- ## 內部函數命名約定 1. **為了避免沖突,外部API函數應該用'php_modulename_function()' 這種形式命名** 并且小寫,用下劃線分割. 對外暴露的API必須定義在你自己的 'php_modulename.h'頭文件中. 例如 : `PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);` 不對外暴露的api不要定義在你的'php_modulename.h' 頭文件中,而且應該用 static關鍵字修飾. 例如 : `static int php_session_destroy(TSRMLS_D)` 2. **主模塊的源文件必須命名為 'modulename.c'.[ modulename 是你自己起的模塊的名字 ]** 3. **主模塊的頭文件被包含在其他的源文件中,必須命名為'php_modulename.h'.** --- ## 語法和縮進 1. **不要使用C++風格的注釋(也就是 // 注釋)** 用C風格的注釋去代替它. PHP是用C寫的, 并且意圖在任何 ANSI-C 編譯器下編譯 . 盡管許多編譯器能夠支持在C代碼中使C++風格的注釋, 但是為了確保你的代碼兼容所有編譯器最好還是使用C風格的注釋 . 唯一例外的是在win32下的代碼, 因為Win32 使用的是 MS-Visual C++ ,這個編譯器是明確支持在C代碼中使用C++風格注釋的 . 2. **使用K&R 風格. 當然我們不能也不想強迫任何人用或不用這種風格** 但是最起碼, 當你寫的代碼提交到PHP的核心或標準模塊之一時, 請保持 K&R 風格 . 這種風格可以應用到所有事物中去, 上到函數聲明語法下到縮進注釋風格 . 也可去看縮進風格 Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 3. **慷慨的空格和括號** 變量的聲明和語句塊之間留一個空行, 同樣在代碼邏輯語句塊之間也要有空行. 兩個函數之間留一個空行,兩個更好 : ```code if (foo) { bar; } to: if(foo)bar; ``` 4. **使用tab制表符進行縮進,一個tab占用四個空格** 5. **預處理語句(例如 #if)必須寫在第一列,如果要縮進預處理語句也要把 # 號放在一行的開始, 緊接著是任意數量的空格.** --- ## 測試 1. **PHP擴展應該用*.phpt 來測試. 請閱讀 README.TESTING.** --- ## 文檔和可折疊鉤子(Documentation and Folding Hooks) 為了確保在線文檔與代碼保持一致 , 每個用戶級函數在有它的用戶級函數原型之前,應該有一行簡單的對函數的描述 . 它看起來應該是這樣的: ```c /* {{{ proto int abs(int number) Returns the absolute value of the number */ PHP_FUNCTION(abs) { ... } /* }}} */ ``` 在Emacs 和 vim 中符號 {{{ 在折疊模式下默認是折疊符號 (set fdm=marker) . 在處理大文件的時候折疊是非常有用的, 因為你能快速滾動文件并展開你希望工作的功能 , 符號 }}} 在每個函數的結尾標志著折疊的結束, 并且應該在單獨的一行 . 那里的"原型(proto)"關鍵字只是輔助doc/genfuncsummary腳本生成所有函數摘要的 , 該關鍵字在函數原型的前面允許我們放在折疊塊里,不影響函數摘要 . 可選參數像下面這樣寫: ```c /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]]) Returns a header object with the defined parameters */ ``` 沒錯, 請保持原型在單獨的一行, 即使這行可能會很長. --- ## 新的或實驗性的函數在首次公開一套新的函數集實現時 , 為了減少相關問題有人建議在這個函數的目錄包含一個有“實驗”標簽的文件 , 并且這個函數在最初實現的時候要遵循下面的標準前綴約定 . EXPERIMENTAL文件應包括以下信息: * 任何編輯信息(已知的bugs, 模塊的未來方向) * 不適合用git comments的當前的狀態記錄一般新特性應該提交到PECL或實驗分支,除非有特殊原因會直接添加到核心發布 --- ## 別名 & 遺留文檔(Aliases & Legacy Documentation) 對同一個名稱，你也可能有一些棄用的別名, 例如 somedb_select_result and somedb_selectresult 文檔只會記錄最新的名字, 別名會記錄在父函數的文檔列表中. 為了便于參考，對于功能相同的名稱不同的用戶函數（如highlight_file和show_source），應分別描述說明。描述函數別名的原型仍應包括在內 , 只要這部分代碼能夠被維護, 功能和名稱應該盡可能保持向后兼容 --- --- # **原文::** --- --- ```code ======================== PHP Coding Standards ======================== This file lists several standards that any programmer adding or changing code in PHP should follow. Since this file was added at a very late stage of the development of PHP v3.0, the code base does not (yet) fully follow it, but it's going in that general direction. Since we are now well into version 5 releases, many sections have been recoded to use these rules. Code Implementation ------------------- 0. Document your code in source files and the manual. [tm] 1. Functions that are given pointers to resources should not free them For instance, ``function int mail(char *to, char *from)`` should NOT free to and/or from. Exceptions: - The function's designated behavior is freeing that resource. E.g. efree() - The function is given a boolean argument, that controls whether or not the function may free its arguments (if true - the function must free its arguments, if false - it must not) - Low-level parser routines, that are tightly integrated with the token cache and the bison code for minimum memory copying overhead. 2. Functions that are tightly integrated with other functions within the same module, and rely on each other non-trivial behavior, should be documented as such and declared 'static'. They should be avoided if possible. 3. Use definitions and macros whenever possible, so that constants have meaningful names and can be easily manipulated. The only exceptions to this rule are 0 and 1, when used as false and true (respectively). Any other use of a numeric constant to specify different behavior or actions should be done through a #define. 4. When writing functions that deal with strings, be sure to remember that PHP holds the length property of each string, and that it shouldn't be calculated with strlen(). Write your functions in such a way so that they'll take advantage of the length property, both for efficiency and in order for them to be binary-safe. Functions that change strings and obtain their new lengths while doing so, should return that new length, so it doesn't have to be recalculated with strlen() (e.g. php_addslashes()) 5. NEVER USE strncat(). If you're absolutely sure you know what you're doing, check its man page again, and only then, consider using it, and even then, try avoiding it. 6. Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend part of the source. Although the ``PHP_*`` macro's are mostly aliased to the ``ZEND_*`` macros it gives a better understanding on what kind of macro you're calling. 7. When commenting out code using a #if statement, do NOT use 0 only. Instead use "<git username here>_0". For example, #if FOO_0, where FOO is your git user foo. This allows easier tracking of why code was commented out, especially in bundled libraries. 8. Do not define functions that are not available. For instance, if a library is missing a function, do not define the PHP version of the function, and do not raise a run-time error about the function not existing. End users should use function_exists() to test for the existence of a function 9. Prefer emalloc(), efree(), estrdup(), etc. to their standard C library counterparts. These functions implement an internal "safety-net" mechanism that ensures the deallocation of any unfreed memory at the end of a request. They also provide useful allocation and overflow information while running in debug mode. In almost all cases, memory returned to the engine must be allocated using emalloc(). The use of malloc() should be limited to cases where a third-party library may need to control or free the memory, or when the memory in question needs to survive between multiple requests. User Functions/Methods Naming Conventions ------------------ 1. Function names for user-level functions should be enclosed with in the PHP_FUNCTION() macro. They should be in lowercase, with words underscore delimited, with care taken to minimize the letter count. Abbreviations should not be used when they greatly decrease the readability of the function name itself:: Good: 'mcrypt_enc_self_test' 'mysql_list_fields' Ok: 'mcrypt_module_get_algo_supported_key_sizes' (could be 'mcrypt_mod_get_algo_sup_key_sizes'?) 'get_html_translation_table' (could be 'html_get_trans_table'?) Bad: 'hw_GetObjectByQueryCollObj' 'pg_setclientencoding' 'jf_n_s_i' 2. If they are part of a "parent set" of functions, that parent should be included in the user function name, and should be clearly related to the parent program or function family. This should be in the form of ``parent_*``:: A family of 'foo' functions, for example: Good: 'foo_select_bar' 'foo_insert_baz' 'foo_delete_baz' Bad: 'fooselect_bar' 'fooinsertbaz' 'delete_foo_baz' 3. Function names used by user functions should be prefixed with ``_php_``, and followed by a word or an underscore-delimited list of words, in lowercase letters, that describes the function. If applicable, they should be declared 'static'. 4. Variable names must be meaningful. One letter variable names must be avoided, except for places where the variable has no real meaning or a trivial meaning (e.g. for (i=0; i<100; i++) ...). 5. Variable names should be in lowercase. Use underscores to separate between words. 6. Method names follow the 'studlyCaps' (also referred to as 'bumpy case' or 'camel caps') naming convention, with care taken to minimize the letter count. The initial letter of the name is lowercase, and each letter that starts a new 'word' is capitalized:: Good: 'connect()' 'getData()' 'buildSomeWidget()' Bad: 'get_Data()' 'buildsomewidget' 'getI()' 7. Classes should be given descriptive names. Avoid using abbreviations where possible. Each word in the class name should start with a capital letter, without underscore delimiters (CamelCaps starting with a capital letter). The class name should be prefixed with the name of the 'parent set' (e.g. the name of the extension):: Good: 'Curl' 'FooBar' Bad: 'foobar' 'foo_bar' Internal Function Naming Conventions ---------------------- 1. Functions that are part of the external API should be named 'php_modulename_function()' to avoid symbol collision. They should be in lowercase, with words underscore delimited. Exposed API must be defined in 'php_modulename.h'. PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); Unexposed module function should be static and should not be defined in 'php_modulename.h'. static int php_session_destroy() 2. Main module source file must be named 'modulename.c'. 3. Header file that is used by other sources must be named 'php_modulename.h'. Syntax and indentation ---------------------- 1. Never use C++ style comments (i.e. // comment). Always use C-style comments instead. PHP is written in C, and is aimed at compiling under any ANSI-C compliant compiler. Even though many compilers accept C++-style comments in C code, you have to ensure that your code would compile with other compilers as well. The only exception to this rule is code that is Win32-specific, because the Win32 port is MS-Visual C++ specific, and this compiler is known to accept C++-style comments in C code. 2. Use K&R-style. Of course, we can't and don't want to force anybody to use a style he or she is not used to, but, at the very least, when you write code that goes into the core of PHP or one of its standard modules, please maintain the K&R style. This applies to just about everything, starting with indentation and comment styles and up to function declaration syntax. Also see Indentstyle. Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 3. Be generous with whitespace and braces. Keep one empty line between the variable declaration section and the statements in a block, as well as between logical statement groups in a block. Maintain at least one empty line between two functions, preferably two. Always prefer:: if (foo) { bar; } to: if(foo)bar; 4. When indenting, use the tab character. A tab is expected to represent four spaces. It is important to maintain consistency in indenture so that definitions, comments, and control structures line up correctly. 5. Preprocessor statements (#if and such) MUST start at column one. To indent preprocessor directives you should put the # at the beginning of a line, followed by any number of whitespace. Testing ------- 1. Extensions should be well tested using *.phpt tests. Read about that in README.TESTING. Documentation and Folding Hooks ------------------------------- In order to make sure that the online documentation stays in line with the code, each user-level function should have its user-level function prototype before it along with a brief one-line description of what the function does. It would look like this:: /* {{{ proto int abs(int number) Returns the absolute value of the number */ PHP_FUNCTION(abs) { ... } /* }}} */ The {{{ symbols are the default folding symbols for the folding mode in Emacs and vim (set fdm=marker). Folding is very useful when dealing with large files because you can scroll through the file quickly and just unfold the function you wish to work on. The }}} at the end of each function marks the end of the fold, and should be on a separate line. The "proto" keyword there is just a helper for the doc/genfuncsummary script which generates a full function summary. Having this keyword in front of the function prototypes allows us to put folds elsewhere in the code without messing up the function summary. Optional arguments are written like this:: /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]]) Returns a header object with the defined parameters */ And yes, please keep the prototype on a single line, even if that line is massive. New and Experimental Functions ----------------------------------- To reduce the problems normally associated with the first public implementation of a new set of functions, it has been suggested that the first implementation include a file labeled 'EXPERIMENTAL' in the function directory, and that the functions follow the standard prefixing conventions during their initial implementation. The file labelled 'EXPERIMENTAL' should include the following information:: Any authoring information (known bugs, future directions of the module). Ongoing status notes which may not be appropriate for Git comments. In general new features should go to PECL or experimental branches until there are specific reasons for directly adding it to the core distribution. Aliases & Legacy Documentation ----------------------------------- You may also have some deprecated aliases with close to duplicate names, for example, somedb_select_result and somedb_selectresult. For documentation purposes, these will only be documented by the most current name, with the aliases listed in the documentation for the parent function. For ease of reference, user-functions with completely different names, that alias to the same function (such as highlight_file and show_source), will be separately documented. The proto should still be included, describing which function is aliased. Backwards compatible functions and names should be maintained as long as the code can be reasonably be kept as part of the codebase. See /phpdoc/README for more information on documentation. ```