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

[skip ci] Amend coding style (#9797)

Browse source 
- Drop irrelevant rule about // comments since PHP is C99 + GNU extensions
- Add rule about strlen() usage for constant string length calculation
- Minor stylistic changes

Co-authored-by: Ilija Tovilo <ilija.tovilo@me.com>
This commit is contained in:
George Peter Banyard 2022-10-21 18:25:11 +01:00 • committed by GitHub
parent 1ea1b6319e
commit 12abb1f55b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

62
CODING_STANDARDS.md
View file

@ -9,7 +9,7 @@ rewritten to comply with these rules.
1. Document your code in source files and the manual. (tm) 1. Document your code in source files and the manual. (tm)
2. Functions that are given pointers to resources should not free them. 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` For instance, `function int mail(char *to, char *from)` should NOT free `to`
and/or `from`. and/or `from`.
@ -26,16 +26,16 @@ rewritten to comply with these rules.
* 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.
3. Functions that are tightly integrated with other functions within the same 1. Functions that are tightly integrated with other functions within the same
module, and rely on each other's non-trivial behavior, should be documented as module, and rely on each other's non-trivial behavior, should be documented as
such and declared `static`. They should be avoided if possible. such and declared `static`. They should be avoided if possible.
4. Use definitions and macros whenever possible, so that constants have 1. Use definitions and macros whenever possible, so that constants have
meaningful names and can be easily manipulated. Any use of a numeric meaningful names and can be easily manipulated. Any use of a numeric
constant to specify different behavior or actions should be done through constant to specify different behavior or actions should be done through
a `#define`. a `#define`.
5. When writing functions that deal with strings, be sure to remember that PHP 1. 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 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 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 they'll take advantage of the length property, both for efficiency and in
@ -43,25 +43,25 @@ rewritten to comply with these rules.
their new lengths while doing so, should return that new length, so it 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()`). doesn't have to be recalculated with `strlen()` (e.g. `php_addslashes()`).
6. NEVER USE `strncat()`. If you're absolutely sure you know what you're doing, 1. 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.
7. Use `PHP_*` macros in the PHP source, and `ZEND_*` macros in the Zend part of 1. 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_*` 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. macros it gives a better understanding on what kind of macro you're calling.
8. When commenting out code using a `#if` statement, do NOT use `0` only. 1. 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` Instead, use `"<git username here>_0"`. For example, `#if FOO_0`,
is your git user `foo`. This allows easier tracking of why code was where `FOO` is your git user `foo`. This allows easier tracking of why
commented out, especially in bundled libraries. code was commented out, especially in bundled libraries.
9. Do not define functions that are not available. For instance, if a library is 1. 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 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 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. use `function_exists()` to test for the existence of a function.
10. Prefer `emalloc()`, `efree()`, `estrdup()`, etc. to their standard C library 1. Prefer `emalloc()`, `efree()`, `estrdup()`, etc. to their standard C library
counterparts. These functions implement an internal "safety-net" mechanism counterparts. These functions implement an internal "safety-net" mechanism
that ensures the deallocation of any unfreed memory at the end of a request. that ensures the deallocation of any unfreed memory at the end of a request.
They also provide useful allocation and overflow information while running They also provide useful allocation and overflow information while running
@ -106,7 +106,7 @@ rewritten to comply with these rules.
jf_n_s_i jf_n_s_i
``` ```
2. If they are part of a "parent set" of functions, that parent should be 1. 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 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_*`: parent program or function family. This should be in the form of `parent_*`:
@ -128,19 +128,19 @@ rewritten to comply with these rules.
delete_foo_baz delete_foo_baz
``` ```
3. Function names used by user functions should be prefixed with `_php_`, and 1. 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 followed by a word or an underscore-delimited list of words, in lowercase
letters, that describes the function. If applicable, they should be declared letters, that describes the function. If applicable, they should be declared
`static`. `static`.
4. Variable names must be meaningful. One letter variable names must be avoided, 1. 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 except for places where the variable has no real meaning or a trivial
meaning (e.g. `for (i=0; i<100; i++) ...`). meaning (e.g. `for (i=0; i<100; i++) ...`).
5. Variable names should be in lowercase. Use underscores to separate between 1. Variable names should be in lowercase. Use underscores to separate between
words. words.
6. Method names follow the *studlyCaps* (also referred to as *bumpy case* or 1. Method names follow the *studlyCaps* (also referred to as *bumpy case* or
*camel caps*) naming convention, with care taken to minimize the letter *camel caps*) naming convention, with care taken to minimize the letter
count. The initial letter of the name is lowercase, and each letter that count. The initial letter of the name is lowercase, and each letter that
starts a new `word` is capitalized: starts a new `word` is capitalized:
@ -161,7 +161,7 @@ rewritten to comply with these rules.
getI() getI()
``` ```
7. Class names should be descriptive nouns in *PascalCase* and as short as 1. 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
@ -219,28 +219,20 @@ rewritten to comply with these rules.
static int php_session_destroy() static int php_session_destroy()
``` ```
2. Main module source file must be named `modulename.c`. 1. Main module source file must be named `modulename.c`.
3. Header file that is used by other sources must be named `php_modulename.h`. 1. 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 1. Use K&R-style. Of course, we can't and don't want to force anybody to use a
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 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 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 maintain the K&R style. This applies to just about everything, starting with
indentation and comment styles and up to function declaration syntax. Also indentation and comment styles and up to function declaration syntax. Also
see [Indentstyle](http://www.catb.org/~esr/jargon/html/I/indent-style.html). see [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 1. 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:
@ -257,14 +249,20 @@ rewritten to comply with these rules.
if(foo)bar; if(foo)bar;
``` ```
4. When indenting, use the tab character. A tab is expected to represent four 1. When indenting, use the tab character. A tab is expected to represent four
spaces. It is important to maintain consistency in indentation so that spaces. It is important to maintain consistency in indentation so 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 indent 1. Preprocessor statements (`#if` and such) MUST start at column one. To indent
preprocessor directives you should put the `#` at the beginning of a line, preprocessor directives you should put the `#` at the beginning of a line,
followed by any number of spaces. followed by any number of spaces.
1. The length of constant string literals should be calculated via ``strlen()``
instead of using ``sizeof()-1`` as it is clearer and any modern compiler
will optimize it away. Legacy usages of the latter style exists within the
codebase but should not be refactored, unless larger refactoring around that
code is taking place.
## Testing ## Testing
1. Extensions should be well tested using `*.phpt` tests. Read more at 1. Extensions should be well tested using `*.phpt` tests. Read more at