I think I followed most of this document but for me it will be really useful to have concrete examples either linked to, or below each bullet point to illustrate "do this" and "don't do this".
Tangentially, it would also be helpful if those examples eventually made it into Manual:Coding conventions/PHP.
Good examples are a lot of work :) I agree, of course, but making or finding *good* examples will take a long time.
The Coding conventions operate on a much lower level, I don't think the same examples would be useful. The documents should be cross-linked, though.
The Coding conventions operate on a much lower level, I don't think the same examples would be useful. The documents should be cross-linked, though.
They mostly do, but the sections on Visibility and Integration in that document go beyond stylistic concerns. Anyway, yeah, a separate document would be fine as long as it's easy to find from there.