Specific guidance on namespaces

[dana-ross]

We've discovered inconsistencies with how namespaces are applied on some projects. Now that 10up engineers are adopting namespaces more widely in their projects, we should be providing more specific guidelines on how to use them in our projects.

A pull request will be coming after some thought on my end, but I wanted to open an issue to get my thoughts together. Any input is welcome.

We do this to logically organize our code and to prevent collisions in the global namespace

What does this mean to someone with no experience with namespaces? What's the "global namespace"? How do things "collide" there? Was anybody hurt?

Let's explain this more clearly, perhaps with a link to an external resource with a good explanation for beginners.

namespace tenup\Utilities\API;

We need to set a standard namespace for 10up projects, and include general guidance for non-10up developers who want to learn from our docs. I propose we stick with this "tenup" namespace that's already in our best practices, although maybe changed to "Tenup" or "TenUp" for consistency with PSR-compliant projects out there.

From there, I propose the next level of the namespace be the client's name (i.e. "tenup\Tyrell-Corporation") followed by a particular site or product name ("tenup\Tyrell-Corporation\Nexus-6"). Consistent namespace naming on a project helps autocompletion in IDEs like phpStorm, making development more efficient, making engineers more productive and EMs happier. On projects where there is a "shared plugin" with common functionality for different sites, we can call that sub-namespace "Util" or "Common".

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. Also, adding more namespaces means more "use" declarations or long \paths\to\namespaces\in_function_calls() which makes code harder to read.

[dana-ross]

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?)

[scottlee]

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.

[tlovett1]

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.

[johnpbloch]

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.

[dsawardekar]

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.

[dana-ross]

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.