Basic Coding Standards via PSR-1

Yesterday, I talked briefly about a rationale for using PSRs versus the WordPress Coding Standards and the when and why of both. But that doesn’t mean it’s not without its points of confusion especially if you’re just starting with them, right?

By that, I mean: Say you’ve been working with the WordPress Coding Standards for years (because I can relate) and now there’s this whole new set of rules and guidelines to follow. But it’s not like a simple matter of changing some white space and renaming files.

There are other points to follow, and each is outlined in a number, quite literally (PSR-1, PSR-2, and so on), of how something should work.

So when it comes to just the basic coding standards as outlined in PSR-1, what are some problematic areas that we may encounter as WordPress developers?

Basic Coding Standards (And Side Effects)

I’ve no plans to go through each of the documents and rehash what we can already learn by simply reading them, but I think there’s something to be said for taking something that many of us either do or experience and see how this might change within the context of WordPress.

Basic Coding Standards via PSR-1

Take Side Effects from the Basic Coding Standard (or PSR-1), for example:

A file SHOULD declare new symbols (classes, functions, constants, etc.) and cause no other side effects, or it SHOULD execute logic with side effects, but SHOULD NOT do both.

The phrase “side effects” means execution of logic not directly related to declaring classes, functions, constants, etc., merely from including the file.

Personally, I find the second phrase the key to understanding and avoiding side effects in our code as much as possible. That is, anything our classes do should be self-contained or be cohesive with something that may have been injected in some way.

Regardless, finding code that introduces a side effect and cleaning it up shouldn’t be too hard. In fact, I’ll use myself as an example.

Look at this particular piece of code:

This code is straight from Toggle Admin Notices. Granted, it’s simple, and the repository shows a note of how to change it. It demonstrates the point nonetheless though, right?

What’s the solution? This comes in the form of Autoloading (which is also covered in PSR-4). So what if I were to refactor it, so it followed PSR-1 properly? Then one way of refactoring it may look like this:

Is this a great example? Probably not. But there’s more to it than just including files. Including those files is having this single file introduce a variety of side effects.

That means this one file alone is responsible for doing a lot more than just those four lines of code. Think of it as incorporating everything that others files implement. It becomes more complex at that point.

So take that idea and move it into a much larger system and you can see how and why this would be problematic.

Of course, there are alternative ways, as well. And this is but one example. Self-deprecating, too. The point isn’t so much about showing a definitive way to do this but to begin seeding thoughts for how we design, plan, build, and incorporate classes.

What About Views?

When it comes to writing plugins, I’m partial to treating what users will see as views. But there seems to be a catch here: It’s considered a poor practice to include files as it introduces side effects.

So we don’t want to output logic in our classes, but we also want to separate presentation from business logic.

Basic Coding Standards: Views

What are we to do?

The twist … is that we’re going to use object-oriented programming to do it. We’ll design a class that generates HTML using PHP template.

This has been covered in-depth by someone else, and I highly recommend reading that particular post to take the idea of side effects, avoiding them, and incorporating solid practices as much as possible.

…And Assets and Related Files?

I know: The idea of moving away from side effects (let alone identifying them) can be weird at first especially when you think about certain things we’ve done for so long.

And it may raise questions like: Is including JavaScript files or CSS files wrong? That’s probably a topic for a different post. Remember, though, there are core API functions directly related to that, and they may be part of a class strictly responsible for doing that.

If a class’ purpose is to do exactly that and only that and it uses API functions to do it, then I’d say it’s likely okay.

But I digress on that for now (and perhaps it’s a topic for the comments or, again, another post).

Instead, keep your classes lean and purposeful. They should do as PSR-1 states and avoid doing things such as “[declaring] new classes, functions, constants, etc.” and “[executing] logic with side effects.”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.