Characteristics of Good PHP Code

At the time I am sitting in the Las Vegas airport waiting for a very delayed layover flight to San Diego. Wonderful weather causing all sorts of headaches. So I’ve decided to make the best of my time by writing the introductory article to a series of PHP articles. I’ve had this idea for a while, and now I’m going to finally sit down and write it.

A Different Type of Article

Over the years I’ve seen many great tutorials on programming better in PHP. Many start with a number, then with a word like “techniques, practices, patterns, etc,” and end with a phrase like “for better PHP.” Examples like “8 Tips for Cleaner Code,” “5 Practices that make you’re life easier,” and the list goes on. I’ve enjoyed and learned a lot about making my PHP code better. However, there is a subject I’ve never really read or heard about before: characteristics of good PHP code.

What is the difference between characteristic and the other subjects above? To me tips, techniques, and practices are well-defined instructions that are straight forward. They may be advanced topics, but they are well-defined. In lots of ways I think of them as rules to follow.

A characteristic, for me at least, is a more abstract concept. Let me give you an example: readable. Several techniques and practices help towards having more readable. However, if a developers follows a few rules, it doesn’t necessary mean his code will be readable. Characteristics are traits that code have that exists, but aren’t easily defined into a set of rules.

Real Life Example

Lets look at a non-programming example. A person can have the characteristic of being “nice.” We all know nice people, and people who are not nice. A nice person might have a habit of saying hi to their co-workers in the morning. However, just because a person says hi to a co-worker in the morning doesn’t mean they are nice. It is impossible to quantify being “nice” into a set of rules and regulations. Being nice is a so much more than just following a few guidelines, hence it is a characteristic. Its the way a person acts in a large variety of situations.

If I am a person who isn’t nice, but I want to become nice, I can’t just google “10 tips on being nice,” follow them, and declare myself a “nice person.” I can’t just emulate things nice people do and expect the same results. Becoming a nice person requires hard work and serious reflection. I would need to take a step back and continuously analyze my actions over time.

Why Characteristics?

So why list characteristics? Writing great code is so much more than following guidelines. It is impossible to write a book of rules that will guarantee great work, yet so many people take this approach when programming. I’ve met several developers, that while reviewing their code, list rules and guidelines as to why they did everything they did. “I’ve commented every section of code.” “I’ve used the DAL for all the queries.” “I used X pattern for Y situation.” The list goes on, but the code they’ve produced looks, feels, and runs sub-par. The reason I like to focus on characteristics is that is helps me recognize there is more to programming than rules and guidelines. Best practices will only help you out so far. The ultimate test is after everything is said and done, and I review my work, is going through my list of characteristics and seeing if my code follows the list.

Like personal characteristics, programming code with great characteristics can take time and experience. Every year I learn more as I write more. I find weaknesses in my code. I make it a personal goal to improve the quality of my code, and I find it helpful to have a list of characteristics I strive for.

What Characteristics?

So what are desirable characteristics of good PHP code? Here is my own list, in no special order. This article is the first of a series which I will describe how to achieve these characteristics with the your code, and how to evaluate your code. So without further introduction, here is my personal list:

• Readable – Being able to easily read code is vital. Don’t ever assume you will be the only developer to ever read and maintain your code. I can’t think of a single project for the exception of my blog that I have been the only one who worked on it. Readable code has meaningful variables, good comments that help describe what’s going on. However, good variables and comments doesn’t necessarily mean your code is readable.
• Organized – While some people think this is the same as readable, organization is different and crucial to me. Readability is the ability to read your code, however organized code helps you find what your looking for. There are many techniques to help keep your code well organized, but the most important thing is at the end of the day, can your fellow developers find what they are looking for?
• Modular – I hear this word tossed around a lot when talking about programming. However, what really is modular? I like to define it as being able to take a part of your code and use it elsewhere with the least amount of headache.
• Relevant – While I hear a lot about Modular code, I don’t hear a lot about relevant code. While people might consider relevant in the modular or organized characteristic, I find it helps me to separate this out. Relevant to me means that code is where it belongs. Its easy to have code blur together and have purposes mixed. Relevant code means the grouping of code belongs together.
• Efficient – What good is code if it is slow, doesn’t scale, and will have to be re-written? Is being efficient is just following a handful of rules and guidelines?
• Practical – It may be efficient, it be organized, but is it practical? In the past I’ve written the “coolest” class, or so I thought, only to have a fellow developer tell him that my implementation is confusing, and overly complex. While many times we create code that isn’t robust enough, but it is possible to make stuff just complicated, over-designed, or just impractical. Keeping your code practical helps you and your team to make a good solution that is easy to maintain.
• Documented – Code that isn’t well documented will be a time drain. I know many developers who think keeping up documentation slows the development process down. However, without that documentation, the overall development process will suffer. Bringing new developers up to speed, maintenance, even just general development will be slowed down by “figuring stuff out.” Documentation is also more than just having a “wiki” or using comments.
• Longevous – The definition is to live a long life. There are two parts to having longevous code. First of all, when you’ve programmed or maintained some code, ask yourself. “How long will this last? Will this solution work well over time?” Then, the second part which I think is almost never asked: “when the time comes, how easily can I extend, or replace this code?” To often programmers “dig ruts” so-to-speak in projects. They code an aspect of a project that locks them into a situation that is extremely difficult to code out of.
• Secure – All of the time spent on development can be for nothing if it isn’t secure. Security in web development is a must. It doesn’t matter the size of the website, large or small, eventually someone will try to break it. Someone will try to compromise it. The consequences vary, from an annoyance, to destroying the entire business. Making your application secure is a skill all developers need.
• Safe – While some people think of this as the same as secure, for me safe PHP code means it handles errors correctly. Great PHP code handles errors correctly. If a PHP class fails, it should handle the error properly. It should also throw errors correctly when needed. If code is safe, I know that it will behave as it should, and properly let me know when it is not.

This article is the first of this series for me, and I’ll try to write an article for each characteristic. I will start on the top of the list and work my way down. Hopefully I can write one every week, and this can help PHP developers take a broader, overall look at their work. Principles, tips, and techniques are great, the are helpful, but without a broader view of things, developers can still develop sup-par code. Knowing the characteristics of good PHP code can help us strive to ensure we make great solutions. It allows us to sit back and really ask ourselves “does this code really have these characteristics?”