From f45b61b8988b5b2d80dd4a1df7edd04282cf319a Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sat, 18 May 2019 21:39:19 +0200 Subject: [ci skip] Migrate Coding standards docs to Markdown --- CODING_STANDARDS.md | 488 +++++++++++++++++++++++++++------------------------- CONTRIBUTING.md | 2 +- README.md | 2 +- ext/ext_skel.php | 2 +- main/main.c | 8 +- 5 files changed, 261 insertions(+), 241 deletions(-) diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md index 4af03c6bc7..cba2611ecb 100644 --- a/CODING_STANDARDS.md +++ b/CODING_STANDARDS.md @@ -1,156 +1,169 @@ -======================== - PHP Coding Standards -======================== +# 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 fully -follow it, but new features are going in that general direction. Many -sections have been recoded to use these rules. +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 fully follow it, but new +features are going in that general direction. Many sections have been recoded to +use these rules. -Code Implementation -------------------- +## Code implementation -0. Document your code in source files and the manual. [tm] +1. Document your code in source files and the manual. (tm) -1. Functions that are given pointers to resources should not free them +2. 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. + For instance, `function int mail(char *to, char *from)` should NOT free to + and/or from. -Exceptions: + Exceptions: -- The function's designated behavior is freeing that resource. E.g. efree() + * 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) + * 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. + * 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. 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. Use definitions and macros whenever possible, so that constants have + meaningful names and can be easily manipulated. The only exceptions to this + rule are 1 and 2, 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. 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, +6. 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. Use `PHP_*` macros in the PHP source, and `ZEND_*` macros in the Zend part of + the source. Although the `PHP_*` macros 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 "_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. When commenting out code using a `#if` statement, do NOT use `0` only. + Instead use `"_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. 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. +10. 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(). + 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. + 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 ------------------- +## 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:: +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: - 'str_word_count' - 'array_key_exists' + + ```php + str_word_count + array_key_exists + ``` Ok: - 'date_interval_create_from_date_string' - (could be 'date_intvl_create_from_date_str'?) - 'get_html_translation_table' - (could be 'html_get_trans_table'?) + + ```php + date_interval_create_from_date_string + // Could be 'date_intvl_create_from_date_str'? + 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_*``:: + ```php + hw_GetObjectByQueryCollObj + pg_setclientencoding + jf_n_s_i + ``` - A family of 'foo' functions, for example: +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' + + ```php + 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'. + ```php + fooselect_bar + fooinsertbaz + delete_foo_baz + ``` -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++) ...). +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`. -5. Variable names should be in lowercase. Use underscores to separate - between words. +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++) ...`). -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:: +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()' + + ```php + connect() + getData() + buildSomeWidget() + ``` Bad: - 'get_Data()' - 'buildsomewidget' - 'getI()' -7. Class names should be descriptive nouns in PascalCase and as short as + ```php + get_Data() + buildsomewidget() + getI() + ``` + +7. Class names should be descriptive nouns in *PascalCase* and as short as possible. Each word in the class name should start with a capital letter, without underscore delimiters. The class name should be prefixed with the name of the "parent set" (e.g. the name of the extension) if no namespaces @@ -162,161 +175,168 @@ User Functions/Methods Naming Conventions not allowed if they are not widely adopted and recognized as such. Good: - 'Curl' - 'CurlResponse' - 'HTTPStatusCode' - 'URL' - 'BTreeMap' (B-tree Map) - 'Id' (Identifier) - 'ID' (Identity Document) - 'Char' (Character) - 'Intl' (Internationalization) - 'Radar' (Radio Detecting and Ranging) + + ```php + Curl + CurlResponse + HTTPStatusCode + URL + BTreeMap // B-tree Map + Id // Identifier + ID // Identity Document + Char // Character + Intl // Internationalization + Radar // Radio Detecting and Ranging + ``` Bad: - 'curl' - 'curl_response' - 'HttpStatusCode' - 'Url' - 'BtreeMap' - 'ID' (Identifier) - 'CHAR' - 'INTL' - 'RADAR' (Radio Detecting and Ranging) - -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'. + ```php + curl + curl_response + HttpStatusCode + Url + BtreeMap + ID // Identifier + CHAR + INTL + RADAR // Radio Detecting and Ranging + ``` + +## 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`. + + ```c 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'. + `php_modulename.h`. + ```c static int php_session_destroy() + ``` -2. Main module source file must be named 'modulename.c'. +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'. +3. Header file that is used by other sources must be named `php_modulename.h`. +## Syntax and indentation -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. -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](http://www.catb.org/~esr/jargon/html/I/indent-style.html). -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 +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:: + between logical statement groups in a block. Maintain at least one empty + line between two functions, preferably two. Always prefer: + ```c if (foo) { bar; } + ``` to: + ```c 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 at + [qa.php.net](https://qa.php.net/write-test.php) documentation. + +## 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: + +```c +/* {{{ 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. -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. +Optional arguments are written like this: -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. +```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 */ +``` -Testing -------- +And yes, please keep the prototype on a single line, even if that line is +massive. -1. Extensions should be well tested using *.phpt tests. Read about that - at https://qa.php.net/write-test.php. +## New and experimental functions -Documentation and Folding Hooks -------------------------------- +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. -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:: +The file labelled `EXPERIMENTAL` should include the following information: - /* {{{ proto int abs(int number) - Returns the absolute value of the number */ - PHP_FUNCTION(abs) - { - ... - } - /* }}} */ +* Any authoring information (known bugs, future directions of the module). +* Ongoing status notes which may not be appropriate for Git comments. -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. +In general new features should go to PECL or experimental branches until there +are specific reasons for directly adding it to the core distribution. -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. +## 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. -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 the -README in the PHP documentation repository for more information on -documentation. +Backwards compatible functions and names should be maintained as long as the +code can be reasonably be kept as part of the codebase. See the `README` in the +PHP documentation repository for more information on documentation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8a5d0ed94..f975859032 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -246,7 +246,7 @@ included. ## Checklist for submitting contribution -- Read [CODING_STANDARDS](/CODING_STANDARDS) before you start working. +- Read [Coding standards](/CODING_STANDARDS.md) before you start working. - Update git source just before running your final `diff` and before testing. - Add in-line comments and/or have external documentation ready. Use only `/* */` style comments, not `//`. diff --git a/README.md b/README.md index b6ecb033bd..ca5d1a7a6e 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ See further documents in the repository for more information on how to contribute: - [Contributing to PHP](/CONTRIBUTING.md) -- [PHP coding standards](/CODING_STANDARDS) +- [PHP coding standards](/CODING_STANDARDS.md) - [Mailinglist rules](/docs/mailinglist-rules.md) - [PHP release process](/docs/release-process.md) diff --git a/ext/ext_skel.php b/ext/ext_skel.php index 2b800ca5c4..ea8df0ac7d 100755 --- a/ext/ext_skel.php +++ b/ext/ext_skel.php @@ -93,7 +93,7 @@ SOURCE AND HEADER FILE NAME php_extension_name_function() - See also CODING_STANDARDS. + See also CODING_STANDARDS.md. OPTIONS diff --git a/main/main.c b/main/main.c index 54afd23789..a6c51e79f0 100644 --- a/main/main.c +++ b/main/main.c @@ -961,7 +961,7 @@ PHPAPI size_t php_printf(const char *format, ...) /* php_verror is called from php_error_docref functions. * Its purpose is to unify error messages and automatically generate clickable * html error messages if correcponding ini setting (html_errors) is activated. - * See: CODING_STANDARDS for details. + * See: CODING_STANDARDS.md for details. */ PHPAPI ZEND_COLD void php_verror(const char *docref, const char *params, int type, const char *format, va_list args) { @@ -1160,7 +1160,7 @@ PHPAPI ZEND_COLD void php_verror(const char *docref, const char *params, int typ /* }}} */ /* {{{ php_error_docref0 */ -/* See: CODING_STANDARDS for details. */ +/* See: CODING_STANDARDS.md for details. */ PHPAPI ZEND_COLD void php_error_docref0(const char *docref, int type, const char *format, ...) { va_list args; @@ -1172,7 +1172,7 @@ PHPAPI ZEND_COLD void php_error_docref0(const char *docref, int type, const char /* }}} */ /* {{{ php_error_docref1 */ -/* See: CODING_STANDARDS for details. */ +/* See: CODING_STANDARDS.md for details. */ PHPAPI ZEND_COLD void php_error_docref1(const char *docref, const char *param1, int type, const char *format, ...) { va_list args; @@ -1184,7 +1184,7 @@ PHPAPI ZEND_COLD void php_error_docref1(const char *docref, const char *param1, /* }}} */ /* {{{ php_error_docref2 */ -/* See: CODING_STANDARDS for details. */ +/* See: CODING_STANDARDS.md for details. */ PHPAPI ZEND_COLD void php_error_docref2(const char *docref, const char *param1, const char *param2, int type, const char *format, ...) { char *params; -- cgit v1.2.1