Three Quick Tips To Make Your PHP Understandable

Introduction

Producing code that clearly conveys a developer’s intent is key to any well written application.
That not only applies to PHP, but every programming language. Developers
who emphasize the creation of legible code tend to create applications which are easier to
both maintain and expand upon. After seven years of programming in PHP I’ve worked on a variety of
projects where well organized and legible code were set aside for numerous reasons. Some of those
reasons include time constraints, lack of experience, lost enthusiasm, misdirected pre-optimizing,
and the list goes on.

Today we’ll look at three simple methods which are commonly ignored by developers for some,
if not all of the reasons described above. First, we’ll discuss the importance of clean conditional
logic. Second, we’ll look at how you can cleanly output blocks html of in PHP. And finally, we’ll
examine the use of sprintf to convey variables placed in stings more legibally.

Tip #1: Write Clean Logic Statements

Example 1.1: Unclean Conditional Logic

The above statement seems straight forward, but it’s flawed for the reason that the developer
is giving this conditional block too much responsibility. I know that might sound a little weird,
but stay with me.

The type of conditional organization above makes for unnecessarily complex code to
both interpret and maintain. A brace that’s paired with a control structure
hundreds of lines above it won’t always be intuitive for developers to locate.
I prefer the style of conditional logic in example 1.2, which inversely solves the previous example.
Let’s take a look.

Example 1.2: Clean Conditional Logic

This conditional statement is more concise and easier to understand.
Instead of stating: “if my condition is met, perform hundreds of operations, else exit the script”,
it’s saying “if my condition is not met, exit the script. Otherwise, I don’t care about what
happens after that. I am only concerned with stopping execution”. So, by doing this,
you’ve limited the operations that a given control structure has been tasked with, and that will help other
developers quickly understand your code.

Tip #2: Use Less PHP And More HTML With Alternative Syntax

When PHP is tightly intertwined with HTML it can be awful to lay your eyes upon.
Many years ago, while with a previous employer, the development staff and I believed it was a
sin to use straight HTML in PHP files. We believed every file ending in a .php
extension could only contain PHP. In retrospect, I don’t know why we ever did this,
but I have seen other groups adhere to such rules as well. This style made what should have been simple HTML far more complex that it had to be.

Over the past few years the style in which
developers are writing PHP to output HTML has shifted quite a bit. Let’s look at Example 2.1

Example 2.1: No Alternative Syntax, and a Lot of PHP.

This is typical to what I’ve seen in a number of PHP applications.
Though this is a simple example, I am sure you can appreciate how this
method of outputting mostly html can grow out of control. It requires
significantly more developer brain power to determine the code’s
purpose than the example below.

Example 2.2: Less PHP Paired With Alternative Syntax

Here in example 2.2 the same functionality is achieved by using PHP alternate syntax and
less output statements. As you can see, this fashion of interweaving PHP and
HTML can go a long way to increase code readability.

Tip #3: Use “sprintf” and Friends

Example 3.1: Uncleanly Spliced String.

I see these types of indecipherable strings –like this SQL
statement example– all too frequently. The meaning of this query
has been lost due to numerous concatenations and escape
functions; which means developers have to invest a significant
amount of time to comprehend the code.

In order to avoid this this, I use PHP’s sprintf() function. sprintf() is a
function that’s part of a family of functions –referred to as the “printf” family of function–
that substitute designated tokens with arguments to the function.
For example, let’s look at the code in example 3.2.

Example 3.2: Cleanly Assembled String With sprintf()

This method allows developers to regain a sense of the data that
they’re representing. In this particular example the %s token means replace
with a string. There a number tokens such as %d (decimal) and %f (floating point).

Check out PHP’s sprintf manual page
for a more detailed account of what you can do with the “printf” family of functions.

Conclusion

I hope this article has provided some information you find useful.
Making your PHP easy to understand by others
should be a top priority for every developer, and I believe that these three simple tips can serve as a start on that journey.