Improve documentation for contributors

CODING_STANDARDS.md

@@ -1,10 +1,9 @@
 # PHP coding standards
 
-This file lists several standards that any programmer adding or changing code in
+This file lists standards that any programmer adding or changing code in
-PHP should follow. Since this file was added at a very late stage of the
+PHP should follow. The code base does not yet fully follow it, but new
-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
-features are going in that general direction. Many sections have been rewritten to
+rewritten to comply with these rules.
-use 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
+    For instance, `function int mail(char *to, char *from)` should NOT free `to`
-    and/or from.
+    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
+      function may free its arguments (if true, the function must free its
-      arguments, if false - it must not)
+      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
+    meaningful names and can be easily manipulated. Any use of a numeric
-    rule are 0 and 1, when used as `false` and `true` (respectively). Any other
+    constant to specify different behavior or actions should be done through
-    use of a numeric constant to specify different behavior or actions should be
+    a `#define`.
-    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
+In general, new features should go to PECL or experimental branches until there
-are specific reasons for directly adding it to the core distribution.
+are specific reasons for directly adding them to the core distribution.
 
 ## Aliases & legacy documentation
 

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?