Specific guidance on namespaces about engineering-best-practices HOT 6 CLOSED

All functional code should be properly namespaced.

This most likely doesn't refer to functional programming and should be changed to "procedural code", "non-OOP code", or re-phrased completely to keep engineers from getting confused when they google for help.

(maybe "non-template code" is closer to what's meant here?)

from engineering-best-practices.

Totally +1 this idea, Dave. The docs as they stand now don't provide much insight into namespacing beyond the recommendation. I too would like to see further clarification around our internal naming policies for what comes after tenup. And, fwiw, I'm all for moving to TenUp vs. tenup, but only because it looks nicer.

from engineering-best-practices.

Definitely agree we need to standardize how we namespace. Thanks for this Dave. Everything sounds good to me. I also like the idea of camelcasing like PSR standards. Would love to hear from some leads on this. CC @johnpbloch @ericmann

We could also use some guidance on how to add to the Window object in JS.

from engineering-best-practices.

This is an excellent topic to discuss. Thanks for doing the legwork on this, @daveross.

I think requiring a \<Vendor>\<Client>\<Project> format as the standard for our namespaces within projects is a great recommendation.

Theme code and plugins within a project can share a namespace. If there's a collision inside that namespace, it's a sign we probably have redundant code, not a prompt to create a new namespace.

I do not agree with this assessment as a standard. If that is the way engineers working on a particular project wish to operate, I think that should be allowed, but I don't think it should be at the cost of prohibiting sub-namespaces inside a project. A few of the major benefits I've seen from using sub-namespaces within projects I've worked on, for example:

• It's necessary for compliance with PSR-0/4, which, regardless of whether autoloading is actually used, provides immediate knowledge of the location of a function or class without needing to use an IDE (e.g. TenUp\Foo\Bar\Baz class is found in ./lib/bar/baz.php, if following PSR-4).
• Discrete features can occupy their own namespace without fear of collision or unnecessary prefixing. As a side effect of this, discrete features become much more portable because all of the code is contained in one siloed place.
• Namespaces can denote the subpackage, while function and class names are free to describe only their purpose within the package. I find this preferable to prefixing functions/classes, which forces readers to filter names in order to discern purpose.

Again, I don't think the coding standard should be too opinionated about whether a team uses One Namespace to Rule Them All vs. Sub-Namespace AllTheThings. Some projects do better with one or the other.

Also, adding more namespaces means more "use" declarations or long \paths\to\namespaces\in_function_calls() which makes code harder to read.

I would almost go so far as to suggest that we require use statements for every class or namespace used in a file as a mandatory part of the coding standards. This practice forces engineers to explicitly declare their code's dependencies at the top of the file where it will be the first thing read by any future maintainers.

Almost.

from engineering-best-practices.

This is an important discussion. I also prefer shallow namespaces as much as possible. And PS-4 which allows greater flexibility without enforcing directory requirements.

Also while standardizing on namespaces we should provide guidance on the Autoloader to use. Using PSR-0 and PSR-4 in different modules for the same namespace is incompatible. We should standardize on one.

Agree with @johnpbloch on side benefits of the use declaration. Knowing the dependencies of a piece of code is great for getting a quick overview of the design.

There are some minor formatting guidelines on this in PHP coding standards which are quite reasonable to include.

When present, there MUST be one blank line after the namespace declaration.
When present, all use declarations MUST go after the namespace declaration.
There MUST be one use keyword per declaration.
There MUST be one blank line after the use block.

from engineering-best-practices.

Stale issue. Not sure specific guidance on namespaces is needed at this point. Team seems to be handling them pretty responsibly and the new theme/plugin scaffolds set a baseline for namespaces on future projects.

from engineering-best-practices.