When Coding, Make the Smallest Possible Change

learn wordpress development basics

After you develop for a while, and especially if you keep an ear out for wisdom that others offer, you get some habits. Those habits aren’t things you consciously think about, but they can make a big difference. I recently discovered that one such habit I have is that I always want to make the smallest possible change to the code I can. This often leads to simpler solutions. Today, I’m going to try to explore that intuition in a way that I hope will convince you of it being right.

This isn’t an article about PHP or JavaScript. Or about any other programming language. It’s instead about a general rule that you can apply to any programming you do. It’s a small thing, but the small things are often the big ones at the root of it. This is one of those: making the smallest changes you can makes much better code, over time.

A Story of Pairing

I was recently pairing with Fred, trying to fix an issue with my Require Featured Image plugin. The bug is caused, to my mind, by a JavaScript bug in Chrome. The executive summary of the relevant bit of code is that the plugin runs some JavaScript to check the HTML of the post-editing screen to see if a featured image is attached, and if that featured image is big enough.

That was mostly working, but every once in a while in Chrome (on both Mac and Windows) the message would flash in for a second when you’d done nothing to the featured image. (This behavior doesn’t happen in Firefox. Because Firefox is a superiors browser in every way. ;p )

What happened, we discovered, is that every once in a while Chrome would screw up when checking the image size for us. It would report that an image was 0px be 0px, when it wasn’t, for no discernible reason. This happened very intermittently, and after about 30 minutes trying to find the underlying cause we settled on the need to just work around it.

The Workaround We Found

We needed to not trust every size-check on an image (because that’s where Chrome was failing), and instead take some rolling average of recent size checks. If the image size was wrong three times (calling on our expert knowledge of American baseball) we’d call it “out.” But if only two of the last three reports were that it was too small, we’d not show the warning.

The functionality of the JavaScript in the plugin is composed of relatively small functions. The core run-time is an every-800-millisecond run of a function which checks if the existing image conditions are met, and shows an error if they are not.

But Where to Put the Fix?

What I should have said, but didn’t is “But if a doctor gave you drugs rather than fixing the broken bone in your leg, you’d be pretty upset and confused, no?”

Needing to change when the message appeared based on the new three-strikes rule, Fred advocated we write that stuff right into this main event loop.

I said no. We went a level deeper. The condition-checking of the featured image is itself a two-branch process. If there is no featured image, it shows a “no image” error. If there is an image, it checks its size and shows an error if it’s too small. If those two check pass, it gives a passing signal.

Here is where we should put the “three strikes” code, Fred said.

“I don’t think so I said. This still isn’t the place.” (I come across in this story as a sage. That’s at least partly because I wrote and rewrote all of this code, Fred had more-or-less never seen it. It’s also because I’m telling this story now.)

“I want to put the three-strikes code in the function that checks the image size,” I said.

“Why?” Fred insisted.

“To put the corrective as close as possible to the cause.”

“But if you break your leg, you don’t reach into your leg to fix it. You go the hospital.”

What I should have said, but didn’t, is “But if a doctor gave you drugs rather than fixing the broken bone in your leg, you’d be pretty upset and confused, no?” What I said instead was something that got us onto trying it the way I wanted–I think by just asking that we try it my way.

We tried it my way. We both thought that it was better.

Why We Put the Code Where We Did

Nearly all of the code changes we made were isolated to the part of the code that was about checking that the image was the right size. To my mind, it was self-evident that that was where we should put it. Here are the reasons I thought so:

  • The error we were seeing is that “the image is too small” when it wasn’t. So we should change the code that checks the image’s size.
  • We ended up needing to create a global variable about the status, for ease of dealing with data persistence across a relatively small JavaScript file. I think this misled Fred, but the fact that the data was global didn’t mean anything other than the size-checking subsystem needed to know about it.

This whole situation just highlights for me that you want to isolate your code from other effects as much as you can. This is the lesson I’ve learned from functional programming, and it’s also something that most established object-oriented programming advice eventually gets you to.

You Used a Global Variable?!

Because this is code I maintain alone, and because we are scoping the global to the plugin-local function-wrapper, I have no concerns about using an “evil” global.

One of the core motives for me telling this story is that the problem with the code kind of affected the whole sub-system we were playing in. We solved the problem by creating a global variable in our JavaScript file.

But I wanted as few actors as possible touching that global state. If you hear much about global state, you’ll probably hear that it’s generally bad. And that’s not wrong. But you must understand the reason that it’s bad. That problem is not that it exists, but that when it exists almost everyone will try to use it.

Because this is code I maintain alone, and because we are scoping the global to the plugin-local function-wrapper, I have no concerns about using an “evil” global.

Thinking About Code is More Important than the Code

I decided, as a writerly choice, to not include the code in this piece. I understand that probably has upset at least a few of you a little. You come here for code, not stories.

But programmers are humans. Humans who understand through stories. I hope you learn something from this story (other than my inerrant wisdom). It’s useful to localize changes, and sometimes a global variable is sufficiently localized. Those are my two “morals” of the story.

I hope this helps you!


0 Comments
Inline Feedbacks
View all comments