Avoid Elegant Code: Use These 3 Principles Instead
There are terabytes of poorly written code in the Internet's Joomla population. This is because of the nature of Joomla as an extensible application. It's wonderful because anyone can create a solution for it and it's horrible because anyone can create a solution for it. Because Joomla sites interweave the efforts and knowledge of hundreds of developers across space and time the highest virtue that its code can aspire to is cleanliness. If you've never heard of code referred to as clean, what it boils down to is simply code that is easy to read, write, and maintain. In this article, will look at why elegant code should be avoided and three simple principles to writing good, clean, Joomla code.
Elegance is a Terrible Goal
Most developers have heard of other programmers work given the highest praise of, "elegance." A programmer is so brilliant that they code they write is marvelously efficient.
Elegance is a crap goal to aspire to.
Trying to create elegant code is a self-indulgent exercise in creating a clever system that reflects your unique intelligence. Most of the time it results in a mess that no one but you understands and even you won't understand a year later.
Aim instead to write clean code first and let elegant solutions emerge only where and when they're needed through the process of re-factoring.
3 Simple Principles for Cleaner, Better, Joomla Code
Here are three principles to follow to creater cleaner Joomla code.
#1 Be Atomic.
Everything in your code should be broken down to its component parts. You want your methods and classes to only do one thing. This is why we call it atomic: you can't break it down any further.
For example, if you have a model that represents an event, it should only have methods that deal with a singular event: save event, delete event, update event, add participant.
Adding a participant is something that an event needs to do. Whereas changing a participant name is something that should be in a participant model because that doesn't have anything to do with the event itself. Likewise, a method for listing all events should not be in the event model because it deals with multiple events and not a single event.
This approach to organization will have you adding a few more classes to your extensions. However, the effect that this has on methods is more striking. When a method can only do one thing, it becomes much shorter and denser than methods that you see in the wild- often just 8 - 12 lines. If you have a method that is 40 plus lines you can be confident that it's doing more than one thing and needs to be re-factored into its atomic parts.
The one thing that some methods will do is manage other methods that all do one thing.
For example, adding a participant might require getting the participant id, saving them as registered in the database, and sending a notification email. The add participant method would call each of these three as separate methods instead of jamming them into one big method.
When every class, method, and function only does one thing clear lines of organization begin to appear. Extraneous code disappears. Instead of seeing a mass of goo that works, you see something that looks closer to legos with specific parts creating a clearly understandable composite whole.
#2 Name Carefully.
If you organize your classes and methods into atomic parts you are only halfway to clarity. The other critical aspect is well considered names. When looking at a method, property, function or class it should be immediately clear what it does. Brevity and generalities are the enemy. You want to be explicit and specific.
- A bad method name: function srtitems($b)
- A good method name: function remove_unpaid_participants ($participant_list)
Methods should read like sentences. If you spot an "and" in your sentence that it's very likely that the method is not atomic and needs to be re-factored into multiple methods.
The Significant Other Test
Once you've implemented these two recommendations, you should be able to perform what I call The Significant Other Test.
The idea behind clean code is that you should be able to walk away from it for a year and come back later and make any changes needed without getting a headache. Unfortunately, because time machines don't exist, this is a difficult proposition to test.
Instead, what you can do is ask your non-coding spouse, boyfriend, or significant other to read your code. They should be able to tell you what the code does even if they can't explain how it's accomplished. (If your code is so hideous that you can't attract a mate, any layperson will do: neighbors, friends, unaccompanied minors... Just so long as they have half a brain and don't know how to program.)
#3 Be Conventional
Joomla has conventions for a reason: use them. Don't create your own templating system, observer pattern, or input validation. Not only is it a waste of your time because it's already been invented, it makes it difficult for other developers to pick up your work, and it removes all of the flexibility and power that Joomla conventions provide.
For example, I've seen directory extensions that use their own templating system to come up with entries to display on the front end. This guarantees that any changes that are needed have to be done by changing the extension. This locks it into that version and requires a developer to perform every update the extension has. If the developers had followed Joomla conventions and used views and layouts, a simple layout override would have sufficed.
Where to from Here?
If you're interested in improving the quality of the code you write, #1 and #2 are basically a few crib notes from smarter people than me. Check out the following book to get an in-depth guide to clean coding with "Uncle Bob":
Once you're comfortable with writing clean code, unit testing and testing driven development are essential follow-on subjects.
To close things out, remember that elegant code is beautiful, but beauty is not the goal of software: utility is. So don't endeavor to be an artist, endeavor to be a craftsman.