RFC: OOPS-WP as Dev Standard

[blobaugh]

We need to decide if OOPS-WP is going to be the base of future dev work.

This ticket is an extension of the debate happening on the BEE call. Use this ticket to document your thoughts/ideas/dreams/wishes/desires/dinner.

The conversation will be centered here, moderated by Aaron and Ben.

---

Comments will be closed on April 19, 2019. After that time Aaron and Ben will have a pow-wow to finalize the direction WDS will head.

---

Please read the notes from the April 4, 2019, BEE Scrum Agenda before contributing: https://docs.google.com/document/d/18gtJcw_zAYlcE7zV5kmDJWDiUYjJGzhU0RzkLKDhWZY/edit#

[aubreypwd]

I think OOPS WP is the future of code at WDS! Major props to @jmichaelward for designing and bringing OOPS WP to us!

I do, however, have concerns about certain implications:

Adherence to WordPress's own Coding Standards

I'd like to see OOPS WP adhere as-close-to-100% to WordPress Coding Standards.

I think we have a responsibility to WordPress as a whole to keep our code familiar and easy to work with within the WordPress community. I'd like to see everything exhausted to keep OOPS WP as adherent as possible to the expectations in the WordPress community.

Our code is mainly for clients, but those clients move on, sometimes they hire not-as-proficient developers to work on their sites. Although we would always hate to lose a client, we can always help them by telling them their code is WP standard code and they can take it anywhere and it's familiar and standard.

Our code sometimes becomes plugins and themes or parts of plugins and themes that might end up out there in the WP.org world. Again, or code should remain familiar, and easy to dive into.

Making it Lean (you use it to do it, but it doesn't tell you how to do it)

When doing OOP with OOPS WP (with my limited experience, mind you), the layers you have to go through to get something to work can get confusing and leave one feeling a bit lost in it all. I worry about things getting more and more abstracted and layered.

I'd like to keep its use lean, simple, and open; more utility-driven than a structure-driven. Leaving the developer to make more decisions on structures vs having to use certain types of structure(s) to design a project.

I don't want to see a base like OOPS WP take away the fun out of coding/designing a project. I want developers to design and build projects, with OOPS WP being more helpful than dictatorial.

Making it Intuitive

For those that aren't OOP-familiar, being presented with a framework like this can be daunting. Terms like "Services," "Interfaces," or "Dependency Injection," etc can all lead to a feeling (speaking through experience) of frustration and even imposter-syndrome.

I'd like to see OOPS WP to feel intuitive to all levels of developers (junior-lead/beginner-advanced) through mindful naming conventions, ground-up documentation, examples, and maybe even generators or helper-functions. A good example is CMB2 which uses OOP, but offers an intuitive path for working with it through helper functions, examples, and good documentation but is still lean enough to do OOP.

Keeping it Democratic

With my experience with WDS Coding Standards I know how the intent to make something democratic doesn't always mean that it ends up that way. Many of the coding standards that have made it in to WDSCS have been complained about afterwards, yet when it came time to vote or voice concern earlier..... (@since hint-hint), 🦗...

We def. need strong drivers to continue to keep OOPS WP democratic at WDS and that's why I like the idea of keeping @aaroneaton and @blobaugh as an unbiased team of moderators who will listen and aggregate all the points of view, concerns, etc, and ensure that all of WDS as-a-whole gets a chance to speak their mind and get properly heard.

Everyone should feel like they are a part of the decision making...

---

But, other than those concerns, I think OOPS WP is our future and I'd like to see it get used over the already outdated Plugin Generator FOR SURE! The helpfulness potential of OOP and what OOPS WP is destined to become has so much potential to make building things fun, fast (as we build more and more helpful things into it), modern, and team-oriented.

[jmichaelward]

As the sole author of this library, it makes me feel somewhat uncomfortable to publicly have WDS internal discussions about how or whether it should be used in our development context since its principles are so firmly rooted in the way I write code. Instead, I've opted to publish a blog post describing what OOPS-WP is and why I developed it so the rest of you can reference it for your consideration.

Thanks.

[aubreypwd]

Use Underscore_Style_Classnames vs. CamelCaseClassnames

Classnames would follow Underscore_Case_Names vs CamelCaseNames which is compatible with OOP and PSR4 (as far as I understand) and would closely resemble WP classes e.g. WP_Post etc.

Ditch class-my-class.php style filenames (only when using OOP)

I've looked into it, and I don't think there is a way to have class- based names like class-my-class.php for a class called My_Class in PSR4 autoloading, etc. So, I think the best compromise here is sticking to PSR4 structures is good, e.g. /My_Class/My_Class.php but we will have to modify WDS Coding Standards to somehow accept this:

I suggest we look at the file, if it's in src/ we exclude this rule. But, in any other case the class-my-class.php rule would still apply (e.g. not OOP project), e.g. in themes and old stuff.

---

I would like to see these end up in the RFC.

[jmichaelward]

I would like to hear pros and cons for underscore style class names versus camel cased names. Although the published WordPress coding documents indicate this as a preference for core development, there's not actually a sniff configured in the WPCS project that checks for it. The only sniff is to check whether you're using the class- prefix in your file names.

Using CamelCase as an object naming convention, as I see it, has three major benefits:

1. It is more concise than Underscore_Naming.
2. It prevents potentially having a mix of directories with underscore_naming and hyphenated-naming.
3. CamelCasing visually separates method calls (which do have sniffs for underscore naming) from objects, making them quickly scannable (sure, you could argue that capitalization does that, too, but I again refer you to point number one - it's still more concise).

Simply removing the sniff for class- makes this library fully 100% WPCS compliant.

[jmichaelward]

One additional note, while I'm thinking of it: WPCS JavaScript standards indicate camelCase usage as preferred for variable names and such, so if anything, moving away from underscore usage will make these easier to read for the frontend team, if the argument is that we're looking to make this library more accessible for everyone.

[tommcfarlin]

The Bottom Line, First

Above all else, I really like the direction and intention of OOPS WP - from both a code and organization standpoint. I want that to be absolutely clear before I comment on anything else so you know how I view this project (for lack of a better term 🙂).

From Personal Experience

In my experience, whenever a team begins talking about this kind of stuff, it's almost always two conversations in one:

1. What's the coding standard that we're using?
2. Is the code that we have going to be a foundation/library/starter for future projects?

I think it's important to make sure we're distinguishing between the two. I'm going to do my best to that in the rest of this comment.

The Coding Standard

In short, I love it. I'm a fan of PSR (though I'm not religious about standards) but dropping the class- prefix and using CamelCase for classes is so nice.

Secondly, I think the adherence to SOLID is another great move. It will make code easier to write, maintain, and test, because it gives us a grid through which we can make decisions about our work.

For example, when introducing a class, we can ask something like:

What is this class doing?

And if the answer yields more than a single answer, we know that we should be breaking it apart.

Secondly, because of the use of namespaces at WDS, I really like making sure namespaces match a directory structure. So if we have a namespace of: WebDevStudios\Utilities\Factory\FooFactory then there's a directory structure that matches that.

We don't have to do searching for the file because we know where the file lives based on its namespace.

Finally, I think having directories like these are helpful:

assets
|- images
|- javascript
|-- dev
|--- {unminified scripts}
|- css
|-- dev
|--- {unminified sass}
|
src
|- vendor
|- {our namespaced code}
|- ...

It can help do the whole "a place for everything and everything in its place" in a sense that it gives convention over configuration. It gets out of our way and allows us to place things where they belong and then get into writing the business logic we need to focus on.

So this is the first part of the conversation. Namely, it's the coding standard part.

Foundations/Libraries/Starters/etc.

As much as many of us who are back-end engineers love this kind of stuff, it's important to note that having something like a plugin generator is necessary for those working on the front-end from time-to-time.

But we have to be careful: A goal of cloning the repository for making a plugin can become more work than necessary.

The reason I say this is because inevitably, we end up removing stuff we don't need or don't have what we do need. I think the former is more likely to happen than the latter especially as the repository grows. This is because we, as a team, would ideally be adding more interfaces and abstract classes that would then necessitate having to remove them when they aren't necessary.

So having it as a 'starter' or a 'foundation' can be a dangerous place to be because we're actually creating work for ourselves to remove code before even getting started.

If we were to go all the way and do this, then perhaps we should consider a way to develop a way to pull in only what we need via Composer or some other way that's yet to be determined.

All of that is my long way of saying is that I like the standard(s) it's applying and I like what it offers but I'm not necessarily a fan of using it as a foundation. At least not until we iron out how we can do it efficiently.

So What Now?

I think it's important to distinguish between standards and starters. I think the most important thing for us is the standard then we can talk about starters or plugin generators or whatever else may come from it.

Once standards are in place, the other stuff comes second because standards are the pre-requisite for everything else.

Hopefully this comment wasn't a book. Thanks for reading :).

[aubreypwd]

I would like to hear pros and cons for underscore style class names versus camel cased names.

The only pro is that they adhere to already set coding standards we use and WordPress uses. Plus I have a personal dislike for camelCase except for JS, again just because it's similar to what we've done and similar to WordPress CS itself.

Maybe less mental friction, I'd like to subtract one more thing to remember off my mental list :D.

there's not actually a sniff configured in the WPCS project that checks for it.

I think so, I don't think it forces you to use _ style, again, it's just similar to WP e.g. WP_Error, WP_Post, etc. To be honest, if I saw camelCase vs camel_Case used, either is really fine. I just want to be able to write Underscore_Style and not forced into camelCase style as it does deviate from what we usually do and what WordPress CS does.

It is more concise than Underscore_Naming.

Both are concise and aim to be concise, just camelCase reduces it by a few characters at most.

It prevents potentially having a mix of directories with underscore_naming and hyphenated-naming.

I've suggested that we use Class_Name\Class_Name style folders in src/ folder. So yes, outside of that (per my suggestion) we will have a mix. But, sniffs will act accordingly.

CamelCasing visually separates method calls

I agree, capitalization does do that too.

so if anything, moving away from underscore usage will make these easier to read for the frontend team, if the argument is that we're looking to make this library more accessible for everyone.

I'm not sure I'm sold on this sell. Frontenders do not use camelCase in PHP, only in Javascript.

---

Finally, I think having directories like these are helpful:

I agree with this, but I think there will be cases where these will be packaged with the classes themselves e.g. "Libraries" where it could look like:

src
|- My_Class/
|---- My_Other_Class.php
|---- assets
|----- images
|----- js
|----- css
|----- {etc...}

I want to make sure things are flexible enough that assets/images/etc can be packaged in a similar way with their class if need-be.

But I agree that a consensus on this too is needed.

Foundations/Libraries/Starters/etc.

I don't see OOPSWP being a starter, more like a utility. The utilities in OOPSWP will help us adhere to the standards we shell out here, just as you said:

I think it's important to distinguish between standards and starters.

This is the standards, which will guide the development of OOPSWP as a utility.

[aubreypwd]

Notes from call on Thursday, April 11, 2019

• OopsWP is going to be considered a "third package party"
• The standard for OOPSWP should be driven by WDS Coding Standards (which is also being somewhat debated above)

---

My Post Call Notes

The only thing that is really affected here with WDSCS is the class- prefix which came up on the call and is here https://github.com/WebDevStudios/WDS-Coding-Standards/pull/65 which will have something to say with things here.

ClassName vs Class_Name is actually not something that WDSCS cares about, so that discussion is primarily for the OppsWP standard. In which I would like to allow either and keep it open for either use.

Finally, I think having directories like these are helpful:

Revisiting this, I think that maybe the enforcement of this is more of a WDSCS thing than and OOPS WP thing. Maybe not relevant here, other than in my example where maybe a Class might be accompanied by additional assets, etc.

[phatsk]

I know I'm late to comment on here, but I wanted to say that the discussion is great. I have some notes from reading through the above conversation and blog post:

• I'm a big fan of OOPS the more I've been using it, and understanding how I'm separating out the responsibility of the code I'm writing. It's also new and difficult at times to really piece together, but overall I like it.
• I'm also throwing my vote in for CamelCase, and I'm excited to have a different discussion around that, and more proposal-style discussions in general for coding standards (this whole process has been really great).

[jmichaelward]

Closing this discussion, as everyone who initiated the dialogue is no longer with WDS. We can discuss further internally, if needed.