提交 5d37cd97 编写于 作者: A Alex Dowad

Improve documentation for contributors

上级 0d6358f2
# 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
......
......@@ -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?
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册