Examples code style
| From: | Michał Brzuchalski | Date: | Thu, 23 May 2019 07:28:20 +0000 |
| Subject: | Examples code style | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969387246@lists.php.net to get a copy of this message | ||
Hi guys,
When joining to doc team I've put myself a goal to unify manual example
codes and make them better in sense of readability and with unified code
style.
I've been doing some research on code examples and found some which don't
follow any standard.
Going further I've found check-examples.php in scripts folder under
doc-base and thought to create a similar using PHP_CodeSniffer with PEAR
standard slightly adjusted through custom ruleset.xml
My intention is to unify all example codes upon agreed ruleset when the
script is ready to use.
Before I can start with that I do have a few questions regarding examples
code style.
As stated in the tutorial they should follow PEAR but this one is quite old
and doesn't contain all new PHP features.
Also, there are some which are rather a preference than a specific standard..
1. Should examples contain a closing tag?
2. Do we prefer string interpolation instead of concatenation?
3. Do we prefer double-quotes or single quotes when possible?
4. Should examples use print_r or var_dump (right now there is a mix of
both)?
5. Should conditional statements allow implicit true comparisons?
for eg.
if (file_exists()) instead of if (file_exists() === TRUE)
6. Do we allow a new object to not be assigned to variables and used
directly?
for eg. `foreach (new APCIterator('user', '/^counter\./') as $counter)
{}`
7. Should echo statements include "\n" at the end or use PHP_EOL constant
(now there is a mix of both styles)?
for eg. echo '$foobar = 2', PHP_EOL;
8. Should echo statements use concatenation or separated with comma
arguments?
for eg. echo '$foobar = 2', PHP_EOL; instead of `echo '$foobar =
2' .
PHP_EOL;`
9. Do we prefer short array syntax for declaring arrays? And each element
in a new line?
10. Do we allow unneeded blank lines?
IMO They basically make examples longer, but most of the examples are
short and there is no need for extra spaces cause the readability is high
enough.
11. Should inline comments start with capital and end with full-stops?
12. Should private member names follow PEAR and be prefixed with an
underscore? Or is it no longer relevant?
I'd like to hear your thoughts on this.
Should I start with one extension reference directory and publish a patch
through ML to visualise how would it look like?
Cheers,
Michał