[ci skip] Migrate Coding standards docs to Markdown

CODING_STANDARDS.md

@@ -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)
 
-- 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.
 
-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,
     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:
-    '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'?)
+    ```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:
-    '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:
-    'foo_select_bar'
+
-    'foo_insert_baz'
+    ```php
-    'foo_delete_baz'
+    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
+    ```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:
-    'connect()'
+
-    'getData()'
+    ```php
-    'buildSomeWidget()'
+    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'
+    ```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:
-    '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
+    ```
+
+## 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
+    `php_modulename_function()` to avoid symbol collision. They should be in
-    lowercase, with words underscore delimited. Exposed API must be defined
+    lowercase, with words underscore delimited. Exposed API must be defined in
-    in 'php_modulename.h'.
+    `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
+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
-    force anybody to use a style he or she is not used to, but,
-    at the very least, when you write code that goes into the core
-    of PHP or one of its standard modules, please maintain the K&R
-    style.  This applies to just about everything, starting with
-    indentation and comment styles and up to function declaration
-    syntax. Also see Indentstyle.
-
-    Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
 
 3. Be generous with whitespace and braces. Keep one empty line between the
     variable declaration section and the statements in a block, as well as
     between logical statement groups in a block. Maintain at least one empty
-    line between two functions, preferably two.  Always prefer::
+    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
+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
+/* {{{ proto int abs(int number)
    Returns the absolute value of the number */
-  PHP_FUNCTION(abs)
+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
 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]]])
+```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
+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.

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 `//`.

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)
 

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
 

main/main.c

@@ -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;