mirror of
https://github.com/php/php-src.git
synced 2024-11-23 09:54:15 +08:00
[ci skip] Migrate Coding standards docs to Markdown
This commit is contained in:
Peter Kokot
parent
fafcdc4d57
commit
f45b61b898
@ -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 "<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. 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. 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
|
||||
----------------------
|
||||
```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
|
||||
'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'.
|
||||
## 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.
|
||||
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.
|
||||
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
|
||||
-------
|
||||
## Testing
|
||||
|
||||
1. Extensions should be well tested using *.phpt tests. Read about that
|
||||
at https://qa.php.net/write-test.php.
|
||||
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
|
||||
-------------------------------
|
||||
## 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::
|
||||
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)
|
||||
{
|
||||
...
|
||||
}
|
||||
/* }}} */
|
||||
```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 `{{{` 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
|
||||
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::
|
||||
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 */
|
||||
```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 */
|
||||
```
|
||||
|
||||
And yes, please keep the prototype on a single line, even if that line
|
||||
is massive.
|
||||
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.
|
||||
## New and experimental functions
|
||||
|
||||
The file labelled 'EXPERIMENTAL' should include the following
|
||||
information::
|
||||
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.
|
||||
|
||||
Any authoring information (known bugs, future directions of the module).
|
||||
Ongoing status notes which may not be appropriate for Git comments.
|
||||
The file labelled `EXPERIMENTAL` should include the following information:
|
||||
|
||||
In general new features should go to PECL or experimental branches until
|
||||
there are specific reasons for directly adding it to the core distribution.
|
||||
* Any authoring information (known bugs, future directions of the module).
|
||||
* Ongoing status notes which may not be appropriate for Git comments.
|
||||
|
||||
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.
|
||||
In general new features should go to PECL or experimental branches until there
|
||||
are specific reasons for directly adding it to the core distribution.
|
||||
|
||||
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.
|
||||
## 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.
|
||||
|
||||
@ -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 `//`.
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -93,7 +93,7 @@ SOURCE AND HEADER FILE NAME
|
||||
|
||||
php_extension_name_function()
|
||||
|
||||
See also CODING_STANDARDS.
|
||||
See also CODING_STANDARDS.md.
|
||||
|
||||
OPTIONS
|
||||
|
||||
|
||||
@ -961,7 +961,7 @@ PHPAPI size_t php_printf(const char *format, ...)
|
||||
/* php_verror is called from php_error_docref<n> 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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user