Re: Examples code style

From: Date: Thu, 23 May 2019 08:32:55 +0000
Subject: Re: Examples code style
References: 1  Groups: php.doc 
Request: Send a blank email to phpdoc+get-969387247@lists.php.net to get a copy of this message
On Thu, 23 May 2019 at 09:28, Michał Brzuchalski < michal.brzuchalski@gmail.com> wrote: > 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. > Probably the best person to answer this is the PHPDoc Editor Peter Cowburn (@salathe). However I'll give my opinion or what I mostly see. > 1. Should examples contain a closing tag? > I'd say yes as most examples I saw include them. > 2. Do we prefer string interpolation instead of concatenation? > From some recent changes I saw it seems "complex" string interpolation is preferred but I may be wrong. > 3. Do we prefer double-quotes or single quotes when possible? > This depends on 2. > 4. Should examples use print_r or var_dump (right now there is a mix of > both)? > I would say var_dump as it is what I mostly see and it seems like print_r was used initially. 5. Should conditional statements allow implicit true comparisons? > for eg. if (file_exists()) instead of if > (file_exists() === TRUE) > Yes, as IMHO it show behaviour of the language. > 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) > {}` > Pretty sure I already saw something along these lines and I don't see the harm in it. > 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; > I would say to use PHP_EOL makes "more sense". > 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;` > I'm pretty sure I only saw concatenation with echo, only place I haven't is on the doc page of echo showing this behaviour. > 9. Do we prefer short array syntax for declaring arrays? And each element > in a new line? > Either is fine IMHO. > 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. > Yes. They allow longer examples to be more readable and it's not one line which is going to make it long. The point of documentation is to be understandable and readable so this one is a necessity. > 11. Should inline comments start with capital and end with full-stops? > I'd rather have them stop using 'you' as per the doc guidelines if you go thought them, but IMHO I do think capitalising them and having punctuation is better. > 12. Should private member names follow PEAR and be prefixed with an > underscore? Or is it no longer relevant? > I would say no, and not even sure I've seen this been done. > 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ł > I do like the project you plan to do, however as a Doc translator I feel this may bring unnecessary strain on the translation teams. As some languages are already behind on keeping up to date the docs with minor changes such as prototype fixes/changes. Best regards George P. Banyard

« previous php.doc (#969387247) next »