WordCamp Nashville: Clean Code for WordPress

Editor's Notes

• #2: It’s not just other people’s code, it’s your own code, 6 months later But it doesn’t have to be this way
• #4: Same technology that power disqus and google analytics My head was spinning enough already from switching between PHP, JS, and Ruby. Keeping the code clean made keeping track of all the interactions coherent.
• #5: I put “plugins” in the title to draw in developers There are many aspects of coding for WordPress that are unique to WordPress, like the 2 talks before me, about custom layout and customizing the admin area, and you have many resources in the WordPress community for help with topics like that. So that’s not what I’m here to talk about either I’m here to talk about coding principles that apply across languages and across development frameworks. I want to get you thinking about approaches to coding that will help you with WordPress, and beyond WordPress as well
• #6: Code formatting is important, but writing clean code is about much more than that - it’s about how your code is organized, and how clearly it expresses its intent. Good organization and expressiveness are the keys to writing code that is flexible, extensible, and maintainable over time.
• #7: Stroustrup: inventor of C++ Booch: IBM chief scientist Thomas: founder of Object Technology International Feathers: author of Working Effectively with Legacy Code Jeffries: co-creator of XP development Cunnigham: inventor of Wikis
• #9: Doctors take the Hippocratic oath and a set of practices to ensure they practice medicine safely Accounts are expected to do double entry booking, to avoid mistakes Other professions have standards for what it means to practice that profession safely and responsibly. When the pressure is on is when you most want them to adhere to their best practices.
• #10: The software craftsmanship movement is intended to start a conversation about what it means to write code responsibly and cleanly. You don't have to agree with the ideas, but you do need to engage them. Other professions - doctors, lawyers, plumbers, etc have various degrees of government regulation. This will happen with software development if we don’t develop professional standards of our own. The $440 million stock market meltdown last summer by Knight Capital happened because they didn’t test their software properly. Everything from gas pumps to medical devices rely on software.
• #11: The more we rush, the more the code turns into a big ball of mud, making it harder and harder to work with. Keeping the code clean lets us go faster, because clean code is flexible code. Why is it exactly that trying to go fast ultimately makes us slower?
• #12: If you’re working quick and dirty, you’re not writing code that is readable
• #13: But we’re not really aware of how we’re spending our time. Going forward, think about the hours you spend debugging, or trying to figure out messy code. When you’re trying to decide whether you should spend a little more time writing code more cleanly, remember an ounce of prevention is worth a pound of cure
• #15: It’s not up to the project manager or your boss. What would your doctor say if you told her to skip washing her hands, because you’re in a hurry? What would your accountant say if you told him to save some time by no doing double-entry bookkeeping? Part of being a professional is being honest about how long it takes to do something well, and not accepting the option to do it wrong.
• #16: Develop systems in small portions at a time (incremental), through repeated cycles (iterative), and take advantage of what was learned in each cycle (for both features and implementation). This workflow style complements the clean code style. Work on one thing, do it well, then move on to the next thing.
• #17: This is an outline of what’s called an Agile workflow, and not all of them may apply to a typical WP project
• #18: You don’t want this kind of relationship with your clients or your code
• #19: This visual is a great analogy for how you should name your variables and functions
• #21: Imagine a script full of variable names like this - it would be very difficult to understand. Mental translating of obscure names to their real meaning distracts from our ability to get an overall understanding of the code The days when it was important to use short variable names to save memory space are long gone Automated minification tools can shrink javascript code for you when dealing with code being transmitted over slow connections
• #22: This gives us the nouns for code that “reads like well written prose”
• #23: Now we get to the verbs and sentences... Take a minute to read this. Even without knowing the class or the properties, it's clear what this method does. You should use a 21st century IDE, that auto-completes names for you and makes it easy to rename. I use PHP Storm. What don’t you see in this code?
• #24: The revelation for me in learning clean code techniques is that code can be expressive. That it really can “read like well written prose.” Rather than relying on comments to explain your code, the code should explain itself Comments become something you have to maintain, and if they become outdated and no longer describe the current behavior of the code, they become dangerous lies But they are sometimes necessary - for example, you may need to explain why you did something a certain way The point is to stop and think before you write a comment, and ask yourself if instead you can make the code more expressive
• #25: A common occurrence in software projects is “bit rot” - the code gets messier and buggier over time. But how about code that just keeps getting cleaner over time? You can get this by following the “boy scout rule.” Keep your new code clean, and while you’re working it, spend a few minutes cleaning up the code that it works with. Improve a variable name, break up a function that’s too big, eliminate a small bit of duplication, etc. (rule 6.5 would be don’t repeat yourself...) It’s easier to keep your garden healthy and looking nice by weeding it for 10min every day than waiting until it’s a huge overgrown mess.
• #26: Do one thing, do it well, do it only But what does it mean to do just one thing? For methods, this typically means changing the value of only one variable If you are passing more than 2 or 3 arguments into a function or method, you are probably doing more than one thing The more arguments you pass to a function, and the longer it is, the harder it is to test and debug when something goes wrong For classes, it means having a single conceptual responsibility. When projects get big, this is how you keep them manageable.
• #27: It accepts one argument - that’s good It changes only one value - that’s good There are no side-effects - that’s good If....elseif blocks are a red flag. There are 3 different cases being handled here. You could technically call this a violation, but each conditional block contains only one line of code, so breaking this down into more methods wouldn’t really help. But if you see the same conditions being tested over and over in different functions, that’s a sign to do some reorganizing
• #28: The complexity of having 44 classes in my Shashin plugin is justified by its need for flexibility You can support a new viewer or a new photo service simply by creating a new subclass. This is much more maintainable and extensible than a single huge file with deeply nested conditionals and unclear dependencies But if I knew I would never need that kind of flexibility, there would be no justification for creating these layers of abstraction – they would just be needless complexity
• #29: Why am I subjecting you to this awful image?
• #30: my attachment to the community - Philly WordCamp But I’m also part of other communities WordPress is essentially a framework, so this could read “WordPress is a tool to be used, not an architecture to be conformed to” This is from a blog post called “screaming architecture” Looking at Shashin, its files and code scream “photo management and display!”, with names like PicasaSynchronizer and PhotoDisplayer. It does not scream “WordPress plugin” The fact that it is a WordPress plugin is incidental to its design. In fact I used a design called the facade pattern, which removes most of the direct dependencies on WordPress. This makes it possible to re-use outside of WordPress if I wanted to.
• #31: I wrote about this on my blog a few weeks ago I’m talking about the Singleton pattern, continuing reliance on global variables, writing integration tests but calling them unit tests (and having an architecture that precludes actual unit testing), etc. WordPress experience is not a good preparation for work outside of WordPress
• #32: I added this slide this morning, after seeing Eric Brace & Peter Cooper last night at the Station Inn Musicians don’t play only when they’re on stage To get good at something you need time to refine your craft, when you’re not under pressure to perform Imagine if downloading wordpress gave you blisters [my working on bus example]