Don’t dirty the diff: tips for writing cleaner PHP

The WP Crowd
Published: June 30, 2016
Topics:

For better or worse, most programming languages are syntactically flexible. Though writing correct syntax and commands is always necessary, there are often certain shortcuts that we can take. Like most shortcuts, though, they can cost us down the line.

Take two common syntactical shortcuts that we have in PHP: the optional comma, and the optional curly braces. PHP doesn’t always require that we include them both, but we can decide to do so. In both cases, I’m going to argue that it’s better to add them in—before diving into why, let’s go over both briefly.

The optional comma

When writing arrays in PHP, we add a comma after each array item:

The commas after the first and second items are always required; it’s the third item that interests us. Here, we’ve written the array without a final comma; this is valid PHP, and will run just fine. However, PHP will still work if we were to add a comma after that final item.

Doing so, our array looks like this:

This is PHP’s optional comma in a nutshell. It’s an extra comma character that can save time down the line. Before diving into why that is, though, let’s talk about our other syntactical shortcut.

The optional curlies

PHP provides a few ways to notate control structures (if, foreach, etc.):

Note: We could’ve used foreach or any other structure here, but if is easiest to quickly notate.

All three examples work. Developers who aren’t aware of the second and third methods might wonder why.

When parsing your code, PHP looks for certain keywords. When it finds keywords like if, it then looks for a “block” of code to execute in connection to that keyword—this is where it gets interesting. This block of code can come in two main forms: it can be one or more statements, surrounded by curly braces ({}); or it can be a single statement, without braces. Example 1 demonstrates the former situation; Examples 2 and 3, the latter.

It’s better to always provide those curly braces, though, just as it’s better to add the optional comma. The hint I use to remind myself of these best practices is simple: don’t dirty the diff. Let’s look at that hint, and consider why these two practices are so valuable to adopt.

Dirty diffs

Many of us use version control tools (like Git, or SVN) to manage our code. These tools provide us a handy way to see the differences between previous versions of our code and the current one: the diff.

Let’s return to our earlier example, the $my_array array. Say we want to add in a fourth item—let’s look at the diff from the version without the optional comma, and the one with it.

Here’s our diff if we add an item after having left out the optional comma:

Here’s the diff if we had used the optional comma:

What’s different here?

In the first diff, Git tells us that two lines have changed. Odd—we’re only adding one item. But this makes sense: PHP requires a comma after every array item but the last one; if we want to add a fourth item, we need to add the comma that’s missing after the third item, thus modifying two lines. In the second diff, though, we only need to modify one line to add another item, because we used the optional comma when we first created the array.

The same thing happens when we leave out curly braces: if we want to do more than one thing after a control structure (after if, foreach, etc)—say, echo a statement and call another function—then we need to modify three lines: one, the original if statement, to add an opening curly brace; two, our added statement; and three, a final line for the closing curly brace.

The first diff is clearly uglier than the second; there’s a whole line change that we could’ve easily avoided, one which creates visual distraction when reviewing the diff (as one might do when preparing a pull request, or when reviewing one for merge).

Why does this matter, though? Are the aesthetics of diffs really that important?

It’s about more than aesthetics

Leaving out optional commas or curlies doesn’t just create uglier diffs—code becomes harder to read, and harder to maintain.

What if, when adding that fourth item to $my_array, we had forgotten to add the now-necessary comma after the third item? PHP would have thrown an error, which we would’ve had to spend time debugging. Not much time, granted, but it’s wasted time easily prevented. It’s the same with optional curly braces.

Fortunately, you don’t have to take this advice just from me. A few other notable resources advocate these practices, too:

  • The WordPress Coding Standards—if you’re working with WordPress, these are the rules to follow.The Standards advocate for including both optional commas and optional curlies. Furthermore, they provide another good reason for the optional comma: “it makes it easier to change the order of the array”.
  • Similar to the WordPress Coding Standards, the PHP-FIG (PHP Framework Interop Group), which sets out recommendations related to PHP programming in general, notes the following in its Coding Style Guide, PSR–2:

    The body of each structure MUST be enclosed by braces. This standardizes how the structures look, and reduces the likelihood of introducing errors as new lines get added to the body.

Reading best practices manuals or posts will yield much of the same—including optional commas and curlies is widely considered a best practice.

Don’t dirty the diff

There are quite a few good reasons to include these optional commas and curlies, to not dirty the diff:

  • Our code is easier to modify
  • Our diffs are easier to review
  • We follow community-declared best practices

I personally use the “don’t dirty the diff” mantra to remind myself to follow these best practices: when I see a diff with more changed lines than should be necessary, I remember to always add commas and curlies, even if optional. Next time you see a dirty diff, consider doing the same.

Get the latest from The WP Crowd

4
Leave a Reply

avatar
4 Comment threads
0 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
2 Comment authors
WordCamp Winnipeg: Clean Code Copy – Shawn Hooper - WordPress Developer & SpeakerWordCamp Toronto: Clean Code – Shawn Hooper - WordPress Developer & SpeakerShawn HooperJustin Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

newest oldest
Justin
Guest

I agree with the brace, but not so much the trailing comma. It’s valid to say there is potential to miss the comma if adding new element, but i like my diff’s dirty and am not into conformity!

Shawn Hooper
Guest

Great article Lucas. It’s worth noting re: the optional comma, that if you’re using the WordPress Coding Standard (https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/) and PHP Code Sniffer, it will insist on the optional comma. It feels odd at first, but once you get used to it, it makes a lot of sense. I love using your “dirty diff” trick as motivation though.

trackback

[…] Blog Post: Don’t Dirty the Diff – Tips for Writing Clean PHP […]

trackback

[…] Blog Post: Don’t Dirty the Diff – Tips for Writing Clean PHP […]