archive/php-src
1
0
Fork 0
mirror of https://github.com/php/php-src.git synced 2025-08-15 21:48:51 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

[ci skip] Migrate Coding standards docs to Markdown

Browse source
This commit is contained in:
Peter Kokot 2019-05-18 21:39:19 +02:00
parent fafcdc4d57
commit f45b61b898
5 changed files with 249 additions and 229 deletions
Download patch file Download diff file Expand all files Collapse all files

464
CODING_STANDARDS.md
View file

@ -1,156 +1,169 @@
======================== # PHP coding standards
PHP Coding Standards
========================
This file lists several standards that any programmer adding or changing This file lists several standards that any programmer adding or changing code in
code in PHP should follow. Since this file was added at a very late PHP should follow. Since this file was added at a very late stage of the
stage of the development of PHP v3.0, the code base does not fully development of PHP v3.0, the code base does not fully follow it, but new
follow it, but new features are going in that general direction. Many features are going in that general direction. Many sections have been recoded to
sections have been recoded to use these rules. 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 For instance, `function int mail(char *to, char *from)` should NOT free to
to and/or from. 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 is given a boolean argument, that controls whether or not the
the function may free its arguments (if true - the function must free its function may free its arguments (if true - the function must free its
arguments, if false - it must not) arguments, if false - it must not)
- Low-level parser routines, that are tightly integrated with the token * Low-level parser routines, that are tightly integrated with the token
cache and the bison code for minimum memory copying overhead. cache and the bison code for minimum memory copying overhead.
2. Functions that are tightly integrated with other functions within the 3. Functions that are tightly integrated with other functions within the same
same module, and rely on each other non-trivial behavior, should be module, and rely on each other non-trivial behavior, should be documented as
documented as such and declared 'static'. They should be avoided if such and declared `static`. They should be avoided if possible.
possible.
3. Use definitions and macros whenever possible, so that constants have 4. Use definitions and macros whenever possible, so that constants have
meaningful names and can be easily manipulated. The only exceptions meaningful names and can be easily manipulated. The only exceptions to this
to this rule are 0 and 1, when used as false and true (respectively). rule are 1 and 2, when used as `false` and `true` (respectively). Any other
Any other use of a numeric constant to specify different behavior use of a numeric constant to specify different behavior or actions should be
or actions should be done through a #define. done through a `#define`.
4. When writing functions that deal with strings, be sure to remember 5. When writing functions that deal with strings, be sure to remember that PHP
that PHP holds the length property of each string, and that it holds the length property of each string, and that it shouldn't be
shouldn't be calculated with strlen(). Write your functions in such calculated with `strlen()`. Write your functions in such a way so that
a way so that they'll take advantage of the length property, both they'll take advantage of the length property, both for efficiency and in
for efficiency and in order for them to be binary-safe. order for them to be binary-safe. Functions that change strings and obtain
Functions that change strings and obtain their new lengths while their new lengths while doing so, should return that new length, so it
doing so, should return that new length, so it doesn't have to be doesn't have to be recalculated with `strlen()` (e.g. `php_addslashes()`).
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, check its man page again, and only then, consider using it, and even then,
try avoiding it. try avoiding it.
6. Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend 7. Use `PHP_*` macros in the PHP source, and `ZEND_*` macros in the Zend part of
part of the source. Although the ``PHP_*`` macro's are mostly aliased to the the source. Although the `PHP_*` macros are mostly aliased to the `ZEND_*`
``ZEND_*`` macros it gives a better understanding on what kind of macro macros it gives a better understanding on what kind of macro you're calling.
you're calling.
7. When commenting out code using a #if statement, do NOT use 0 only. Instead 8. When commenting out code using a `#if` statement, do NOT use `0` only.
use "<git username here>_0". For example, #if FOO_0, where FOO is your Instead use `"<git username here>_0"`. For example, `#if FOO_0`, where `FOO`
git user foo. This allows easier tracking of why code was commented out, is your git user `foo`. This allows easier tracking of why code was
especially in bundled libraries. commented out, especially in bundled libraries.
8. Do not define functions that are not available. For instance, if a 9. Do not define functions that are not available. For instance, if a library is
library is missing a function, do not define the PHP version of the missing a function, do not define the PHP version of the function, and do
function, and do not raise a run-time error about the function not not raise a run-time error about the function not existing. End users should
existing. End users should use function_exists() to test for the use `function_exists()` to test for the existence of a function.
existence of a function
9. Prefer emalloc(), efree(), estrdup(), etc. to their standard C library 10. Prefer `emalloc()`, `efree()`, `estrdup()`, etc. to their standard C library
counterparts. These functions implement an internal "safety-net" counterparts. These functions implement an internal "safety-net" mechanism
mechanism that ensures the deallocation of any unfreed memory at the that ensures the deallocation of any unfreed memory at the end of a request.
end of a request. They also provide useful allocation and overflow They also provide useful allocation and overflow information while running
information while running in debug mode. in debug mode.
In almost all cases, memory returned to the engine must be allocated In almost all cases, memory returned to the engine must be allocated using
using emalloc(). `emalloc()`.
The use of malloc() should be limited to cases where a third-party The use of `malloc()` should be limited to cases where a third-party library
library may need to control or free the memory, or when the memory in may need to control or free the memory, or when the memory in question needs
question needs to survive between multiple requests. 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 1. Function names for user-level functions should be enclosed with in the
the PHP_FUNCTION() macro. They should be in lowercase, with words `PHP_FUNCTION()` macro. They should be in lowercase, with words underscore
underscore delimited, with care taken to minimize the letter count. delimited, with care taken to minimize the letter count. Abbreviations
Abbreviations should not be used when they greatly decrease the should not be used when they greatly decrease the readability of the
readability of the function name itself:: function name itself:
Good: Good:
'str_word_count'
'array_key_exists' ```php
str_word_count
array_key_exists
```
Ok: Ok:
'date_interval_create_from_date_string'
(could be 'date_intvl_create_from_date_str'?) ```php
'get_html_translation_table' date_interval_create_from_date_string
(could be 'html_get_trans_table'?) // Could be 'date_intvl_create_from_date_str'?
get_html_translation_table()
// Could be 'html_get_trans_table'?
```
Bad: Bad:
'hw_GetObjectByQueryCollObj'
'pg_setclientencoding'
'jf_n_s_i'
2. If they are part of a "parent set" of functions, that parent should ```php
be included in the user function name, and should be clearly related hw_GetObjectByQueryCollObj
to the parent program or function family. This should be in the form pg_setclientencoding
of ``parent_*``:: 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: Good:
'foo_select_bar'
'foo_insert_baz' ```php
'foo_delete_baz' foo_select_bar
foo_insert_baz
foo_delete_baz
```
Bad: Bad:
'fooselect_bar'
'fooinsertbaz'
'delete_foo_baz'
3. Function names used by user functions should be prefixed ```php
with ``_php_``, and followed by a word or an underscore-delimited list of fooselect_bar
words, in lowercase letters, that describes the function. If applicable, fooinsertbaz
they should be declared 'static'. delete_foo_baz
```
4. Variable names must be meaningful. One letter variable names must be 3. Function names used by user functions should be prefixed with `_php_`, and
avoided, except for places where the variable has no real meaning or followed by a word or an underscore-delimited list of words, in lowercase
a trivial meaning (e.g. for (i=0; i<100; i++) ...). letters, that describes the function. If applicable, they should be declared
`static`.
5. Variable names should be in lowercase. Use underscores to separate 4. Variable names must be meaningful. One letter variable names must be avoided,
between words. 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' 5. Variable names should be in lowercase. Use underscores to separate between
or 'camel caps') naming convention, with care taken to minimize the words.
letter count. The initial letter of the name is lowercase, and each
letter that starts a new 'word' is capitalized:: 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: Good:
'connect()'
'getData()' ```php
'buildSomeWidget()' connect()
getData()
buildSomeWidget()
```
Bad: 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, possible. Each word in the class name should start with a capital letter,
without underscore delimiters. The class name should be prefixed with the 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 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. not allowed if they are not widely adopted and recognized as such.
Good: Good:
'Curl'
'CurlResponse' ```php
'HTTPStatusCode' Curl
'URL' CurlResponse
'BTreeMap' (B-tree Map) HTTPStatusCode
'Id' (Identifier) URL
'ID' (Identity Document) BTreeMap // B-tree Map
'Char' (Character) Id // Identifier
'Intl' (Internationalization) ID // Identity Document
'Radar' (Radio Detecting and Ranging) Char // Character
Intl // Internationalization
Radar // Radio Detecting and Ranging
```
Bad: Bad:
'curl'
'curl_response'
'HttpStatusCode'
'Url'
'BtreeMap'
'ID' (Identifier)
'CHAR'
'INTL'
'RADAR' (Radio Detecting and Ranging)
Internal Function Naming Conventions ```php
---------------------- curl
curl_response
HttpStatusCode
Url
BtreeMap
ID // Identifier
CHAR
INTL
RADAR // Radio Detecting and Ranging
```
1. Functions that are part of the external API should be named ## Internal function naming conventions
'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'.
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); PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
```
Unexposed module function should be static and should not be defined in Unexposed module function should be static and should not be defined in
'php_modulename.h'. `php_modulename.h`.
```c
static int php_session_destroy() 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 2. Use K&R-style. Of course, we can't and don't want to force anybody to use a
comments instead. PHP is written in C, and is aimed at compiling style he or she is not used to, but, at the very least, when you write code
under any ANSI-C compliant compiler. Even though many compilers that goes into the core of PHP or one of its standard modules, please
accept C++-style comments in C code, you have to ensure that your maintain the K&R style. This applies to just about everything, starting with
code would compile with other compilers as well. indentation and comment styles and up to function declaration syntax. Also
The only exception to this rule is code that is Win32-specific, see [Indentstyle](http://www.catb.org/~esr/jargon/html/I/indent-style.html).
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 3. Be generous with whitespace and braces. Keep one empty line between the
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 variable declaration section and the statements in a block, as well as
between logical statement groups in a block. Maintain at least one empty between logical statement groups in a block. Maintain at least one empty
line between two functions, preferably two. Always prefer:: line between two functions, preferably two. Always prefer:
```c
if (foo) { if (foo) {
bar; bar;
} }
```
to: to:
```c
if(foo)bar; if(foo)bar;
```
4. When indenting, use the tab character. A tab is expected to represent 4. When indenting, use the tab character. A tab is expected to represent four
four spaces. It is important to maintain consistency in indenture so spaces. It is important to maintain consistency in indenture so that
that definitions, comments, and control structures line up correctly. definitions, comments, and control structures line up correctly.
5. Preprocessor statements (#if and such) MUST start at column one. To 5. Preprocessor statements (`#if` and such) MUST start at column one. To indent
indent preprocessor directives you should put the # at the beginning preprocessor directives you should put the `#` at the beginning of a line,
of a line, followed by any number of whitespace. followed by any number of whitespace.
Testing ## Testing
-------
1. Extensions should be well tested using *.phpt tests. Read about that 1. Extensions should be well tested using `*.phpt` tests. Read about that at
at https://qa.php.net/write-test.php. [qa.php.net](https://qa.php.net/write-test.php) documentation.
Documentation and Folding Hooks ## Documentation and folding hooks
-------------------------------
In order to make sure that the online documentation stays in line with In order to make sure that the online documentation stays in line with the code,
the code, each user-level function should have its user-level function each user-level function should have its user-level function prototype before it
prototype before it along with a brief one-line description of what the along with a brief one-line description of what the function does. It would look
function does. It would look like this:: like this:
/* {{{ proto int abs(int number) ```c
Returns the absolute value of the number */ /* {{{ proto int abs(int number)
PHP_FUNCTION(abs) Returns the absolute value of the number */
{ PHP_FUNCTION(abs)
... {
} ...
/* }}} */ }
/* }}} */
```
The {{{ symbols are the default folding symbols for the folding mode in The `{{{` symbols are the default folding symbols for the folding mode in Emacs
Emacs and vim (set fdm=marker). Folding is very useful when dealing with and vim (`set fdm=marker`). Folding is very useful when dealing with large files
large files because you can scroll through the file quickly and just unfold because you can scroll through the file quickly and just unfold the function you
the function you wish to work on. The }}} at the end of each function marks wish to work on. The `}}}` at the end of each function marks the end of the
the end of the fold, and should be on a separate line. fold, and should be on a separate line.
The "proto" keyword there is just a helper for the doc/genfuncsummary script 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 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 function prototypes allows us to put folds elsewhere in the code without
messing up the function summary. messing up the function summary.
Optional arguments are written like this:: 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]]]) ```c
Returns a header object with the defined parameters */ /* {{{ 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 And yes, please keep the prototype on a single line, even if that line is
is massive. massive.
New and Experimental Functions ## 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 To reduce the problems normally associated with the first public implementation
information:: 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.
Any authoring information (known bugs, future directions of the module). The file labelled `EXPERIMENTAL` should include the following information:
Ongoing status notes which may not be appropriate for Git comments.
In general new features should go to PECL or experimental branches until * Any authoring information (known bugs, future directions of the module).
there are specific reasons for directly adding it to the core distribution. * Ongoing status notes which may not be appropriate for Git comments.
Aliases & Legacy Documentation In general new features should go to PECL or experimental branches until there
----------------------------------- are specific reasons for directly adding it to the core distribution.
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 ## Aliases & legacy documentation
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 You may also have some deprecated aliases with close to duplicate names, for
documentation. 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.

2
CONTRIBUTING.md
View file

@ -246,7 +246,7 @@ included.
## Checklist for submitting contribution ## 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. - Update git source just before running your final `diff` and before testing.
- Add in-line comments and/or have external documentation ready. Use only - Add in-line comments and/or have external documentation ready. Use only
`/* */` style comments, not `//`. `/* */` style comments, not `//`.

2
README.md
View file

@ -123,7 +123,7 @@ See further documents in the repository for more information on how to
contribute: contribute:
- [Contributing to PHP](/CONTRIBUTING.md) - [Contributing to PHP](/CONTRIBUTING.md)
- [PHP coding standards](/CODING_STANDARDS) - [PHP coding standards](/CODING_STANDARDS.md)
- [Mailinglist rules](/docs/mailinglist-rules.md) - [Mailinglist rules](/docs/mailinglist-rules.md)
- [PHP release process](/docs/release-process.md) - [PHP release process](/docs/release-process.md)

2
ext/ext_skel.php
View file

@ -93,7 +93,7 @@ SOURCE AND HEADER FILE NAME
php_extension_name_function() php_extension_name_function()
See also CODING_STANDARDS. See also CODING_STANDARDS.md.
OPTIONS OPTIONS

8
main/main.c
View file

@ -961,7 +961,7 @@ PHPAPI size_t php_printf(const char *format, ...)
/* php_verror is called from php_error_docref<n> functions. /* php_verror is called from php_error_docref<n> functions.
* Its purpose is to unify error messages and automatically generate clickable * Its purpose is to unify error messages and automatically generate clickable
* html error messages if correcponding ini setting (html_errors) is activated. * 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) 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 */ /* {{{ 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, ...) PHPAPI ZEND_COLD void php_error_docref0(const char *docref, int type, const char *format, ...)
{ {
va_list args; va_list args;
@ -1172,7 +1172,7 @@ PHPAPI ZEND_COLD void php_error_docref0(const char *docref, int type, const char
/* }}} */ /* }}} */
/* {{{ php_error_docref1 */ /* {{{ 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, ...) PHPAPI ZEND_COLD void php_error_docref1(const char *docref, const char *param1, int type, const char *format, ...)
{ {
va_list args; va_list args;
@ -1184,7 +1184,7 @@ PHPAPI ZEND_COLD void php_error_docref1(const char *docref, const char *param1,
/* }}} */ /* }}} */
/* {{{ php_error_docref2 */ /* {{{ 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, ...) PHPAPI ZEND_COLD void php_error_docref2(const char *docref, const char *param1, const char *param2, int type, const char *format, ...)
{ {
char *params; char *params;