Day Five: Consistency Over So-Called Superiority

My Fullstack Journal: 1 November 2019

Gemma Black
Nov 2 · 4 min read

Every day. You and I are going to discover better ways of doing things.

Maybe it’s a new innovation.

Maybe it’s a better “best practice”.

Imagine trying to use libraries without a package manager like npm or composer. It’s not impossible. It’s just more laborious in many use cases.

Yesterday, I faced such an issue. A lesson I needed to be reminded of.

CodeIgniter Functions vs My Colleague’s Abstractions

As we use CodeIgniter for one of our older services at Kamma, I decided to use the documented framework functions.

But I knew my dear colleague had made many of his own abstractions on top. But for simplicity’s sake (and a bad superiority mindset), I used CodeIgniter instead. I looked up the documentation, created a new endpoint and coded away.

But there’s a problem.

The code becomes inconsistent

Afterwards, I asked for feedback as you do.

He said (nicely mind), and to paraphrase, “ah, there’s a better way that hooks up with the front end and automatically does polling and integrates with the background workers too. So you don’t have to write a lot of this scaffolding. And it’ll make your life simpler. And it means we’re not duplicating stuff.”

And he’s right for another reason. Consistency.

If in one place, we use one set of abstractions, and in another place a different set, it will cause confusion. More costly, it can lead to duplications where a bug appears fixed, but actually, the bug lives elsewhere because the functionality has been written twice.

But what wrong mindset did I have? “Explicit code is superior”.

Explicit code makes the code clear when you look at it as the specifics of what’s being done is already laid out before you and you don’t have to track down issues elsewhere, but generally means a lot more work writing it — https://blog.codeship.com/what-is-the-difference-between-implicit-vs-explicit-programming/

Yes. Recreating a new custom endpoint with custom code is explicit. But frameworks help the developer focus on the feature and not the scaffold. So balance is needed between implicit convention over explicit code.

Javascript Joel made a great tweet about consistency.

But why is consistency so important?

When I started out as a developer, I didn’t like Angular. Convention over configuration was limiting; oh so I felt. But it’s rather productive when you’re constricted into a handful of ways of solving problems. Michael Bryzek used it to scale his organisation to use microservices in a maintainable way.

And here’s a list of some interesting points by Joseph Grefoh about the need for consistency in our programs:

Predictions about its behavior and implementation…end up being accurate. On larger, older systems where you can’t fit the codebase in your head, these guesses are critical tools developers use to feel their way around the system.

Making a change in one place can affect another. If something breaks in one place, it’s broken everywhere. That’s a good thing. That means it needs to be fixed in one place.

Even if a new approach is objectively better, weigh the tradeoffs with the lack of consistency it will introduce.

Some things are better, but not much better when in context.

Like, writing my own endpoint meant I failed to hook into a polling javascript function. And it is dependable, as in, it works and has been working for years. Why add something new that now needs unit, integration, QA and manual user testing?

If you do use a new approach, ensure that you completely swap out the old approach.

I’d have to change many occurrences of this new polling functionality for a manual more explicit version. It’s not a good use of developer time in comparison to the number of features needing to be developed.

Whether it means uploading images, setting up routes, or iterating over a collection, try to establish The One True Way of doing something.

Having a Readme for an application that discusses The One True Way is so helpful where that way is not obvious. Even more so, going the Michael Brysek route, having a standard you follow as a team across all applications seems very productive to me.

What other issues did this small feature feedback raise?

It highlighted I had a serious knowledge gap in useful abstractions my colleague had already built. So, I decided to start documenting the more complicated abstractions in a little Readme.

So for example, when you need to look up how to create a model in Laravel’s Eloquent or a new middleware in Nodejs’s Express Framework, their Readme will is your goto place for The One True Way of doing things in that codebase.

If you’re like me, always learning more efficient ways of doing this, maybe this article will help you feel better that “choosing consistency over so-called superiority” is not a bad thing.

Gemma Black

Journals, Code, Music and Life as a Startup Developer

Gemma Black

Written by

Chocolate-, brownie-, coding-, peace-loving, city girl who loves both nature and tech.

Gemma Black

Journals, Code, Music and Life as a Startup Developer

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade