From 5d37cd97e4c890fa264277b945249802aa189f2e Mon Sep 17 00:00:00 2001 From: Alex Dowad Date: Sun, 30 May 2021 21:32:40 +0200 Subject: [PATCH] Improve documentation for contributors --- CODING_STANDARDS.md | 53 +++++++++++++++------------------------------ CONTRIBUTING.md | 12 +++++----- 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md index 5754718e5a3..69aff91d6ad 100644 --- a/CODING_STANDARDS.md +++ b/CODING_STANDARDS.md @@ -1,10 +1,9 @@ # 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 rewritten to -use these rules. +This file lists standards that any programmer adding or changing code in +PHP should follow. The code base does not yet fully follow it, but new +features are going in that general direction. Many sections have been +rewritten to comply with these rules. ## Code implementation @@ -12,8 +11,8 @@ use these rules. 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: @@ -21,21 +20,20 @@ use these rules. `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) + 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. 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 + module, and rely on each other's non-trivial behavior, should be documented as such and declared `static`. They should be avoided if possible. 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 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`. + meaningful names and can be easily manipulated. Any use of a numeric + constant to specify different behavior or actions should be done through + a `#define`. 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 @@ -260,35 +258,18 @@ use these rules. ``` 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 + spaces. It is important to maintain consistency in indentation 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. + followed by any number of spaces. ## Testing -1. Extensions should be well tested using `*.phpt` tests. Read about that at +1. Extensions should be well tested using `*.phpt` tests. Read more at [qa.php.net](https://qa.php.net/write-test.php) documentation. -## Folding hooks - -Use `{{{` 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. - -```c -/* {{{ Returns the absolute value of the number */ -PHP_FUNCTION(abs) -{ - ... -} -/* }}} */ -``` - ## New and experimental functions To reduce the problems normally associated with the first public implementation @@ -302,8 +283,8 @@ The file labelled `EXPERIMENTAL` should include the following information: * Any authoring information (known bugs, future directions of the module). * Ongoing status notes which may not be appropriate for Git comments. -In general new features should go to PECL or experimental branches until there -are specific reasons for directly adding it to the core distribution. +In general, new features should go to PECL or experimental branches until there +are specific reasons for directly adding them to the core distribution. ## Aliases & legacy documentation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8784e714470..f8a1abca4ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Anybody who programs in PHP can be a contributing member of the community that develops and deploys it; the task of deploying PHP, documentation and associated -websites is a never ending one. With every release, or release candidate comes a +websites is a never-ending one. With every release or release candidate comes a wave of work, which takes a lot of organization and co-ordination. You don't need any special access to download, build, debug and begin submitting @@ -85,7 +85,7 @@ for additional notes on the best way to approach submitting an RFC. ## Writing tests -We love getting new tests! PHP is a huge project and improving code coverage is +We love getting new tests! PHP is a huge project and improving test coverage is a huge win for every PHP user. [Our QA site includes a page detailing how to write test cases.](https://qa.php.net/write-test.php) @@ -255,14 +255,14 @@ included. - 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 +- Add inline comments and/or have external documentation ready. Use only `/* */` style comments, not `//`. - Create test scripts for use with `make test`. - Run `make test` to check your change doesn't break other features. - Rebuild PHP with `--enable-debug` which will show some kinds of memory errors and check the PHP and web server error logs after running your PHP tests. - Rebuild PHP with `--enable-zts` to check your change compiles and operates - correctly in a thread safe PHP. + correctly in a thread-safe PHP. - Review the change once more just before submitting it. ## What happens after submitting contribution? @@ -270,7 +270,7 @@ included. If your change is easy to review and obviously has no side-effects, it might be committed relatively quickly. -Because PHP is a volunteer-driven effort more complex changes will require +Because PHP is a volunteer-driven effort, more complex changes will require patience on your side. If you do not receive feedback in a few days, consider bumping. Before doing this think about these questions: @@ -278,7 +278,7 @@ bumping. Before doing this think about these questions: - Did I review the mailing list archives to see if these kind of changes had been discussed before? - Did I explain my change clearly? -- Is my change too hard to review? Because of what factors? +- Is my change too hard to review? If so, why? ## What happens when your contribution is applied?