Examples code style

From: 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ł

« previous php.doc (#969387246) next »