eat some code

Premature code reuse

Avoid the delusion of code reuse

August 2016 #code reuse  #engineering  #architecture  #clean code 

Reusing code is one of the first thing we learn in the IT industry. It's common sense, code reuse means it takes a lot less effort to get your application on the market. Everyone wants as much code reuse as possible. Identifying what should be reused is more complex than it seems.

You are already reusing a lot of code

Real developers don't enjoy writing code. This is why we use frameworks and libraries to get most of the work done for us. Frameworks tend to do what's obviously reusable. For example, all backend frameworks (such as Django and RoR) come with an ORM. Building your own ORM would be in 99.99% of cases pure madness.

The fact that we reuse frameworks, CSS pre & post compilers, database engines, plugins and libraries isn't enough. Ideally, we should be able to just configure a stack of plugins together via configuration files and only write code for business logic. Actually, we shouldn't even write a single line of code, UML diagrams and a bit of AI should do the work ! This sounds amazing but this is distant future.

Predicting reusability

A simple example

While designing an application, we often face cases where the code is going to be similar in a few places or in other applications. It often happens when the UX is similar or when the "concept" is the "same". A good example is adding a "News" section to your website. "News" is a simple concept, it's the same things for people, small and large organisations, it's the same thing everywhere in the World. It has to be reusable, right? UX architect, project managers, designers and developers all agree on this:


Let's build a reusable "News" component.

John Doe

Building that reusable code

The decision has been made, this website will include a news feed but instead of being dumb and just coding it without thinking about the future, let's create an awesome plugin: my-great-news-plugin. So we need to build the following:

  • Model:
    • NewsCategory + NewsItem + optional Tags (yeah we'll need this for sure)
    • some queries: news by category, most recent news, etc.
    • let's not forget a field for publication, some apps will use a date, others a checkbox, let's give both options (yeah, we are so clever)
  • View (let's use Twitter bootstrap for reusability):
    • news listing with pagination
    • filtered news listing
    • new detail
    Controller:
    • news listing
    • news detail
    • Admin CRUD section

Applying that reusable code once

You've worked hard on this plugin. It's time to apply it to the actual website. The process is slightly harder than expected since there are now 2 different projects / repositories. Once the work is done the whole team feels great about it; it was totally worth it:

  • Designers can add that news plugin to their portfolio
  • UX architect are serving several customers at once
  • Project managers are sure it will save time in the long run
  • Developers have some open source code to show and can rely on it for the next project
  • Salers can now bundle this great news component for cheap and explain to customers how thoughtful the team is

Applying that reusable code a second time

A few weeks go by and a new website requires a news feed. As expected, there are only a few minor differences:

  • each news item must be attached to their author
  • there is no need for news categories
  • there is no global news page, only widgets within each team member profile page

As a result, the model and the admin have to be overwritten, the admin must be overwritten too. The controllers, the queries and views are useless. The amount of reused code is close to zero. Worst, the code is more complicated than it should be. Indeed, developers now must look at 2 files to know what a News item is made of. They also have to look at 2 files when editing the admin.

The alternative

The issue is simple, the reusability of a news component was incorrectly predicted. I've found that the best way to write reusable code is to see it happen first. When you've almost written the same code 3 times, you can then refactor it. It's really similar to the TDD principle where you get things working before refactoring. Just like TDD, it's a counter-intuitive but a much better approach.

You want to wait until reusability becomes obvious.

No seasoned developer will make the mistake of trying to write a reusable news component. It's however a lot harder to resist the temptation to write generic code first when writing a few classes. In Django, a classic example is when News and Events are really similar and you want to start by writing a base Model and some basic Class Based Views for these. By doing this, you'll save about 20 lines of code. In version 2 of the website, News & Events differences will grow making that initial decision completely pointless.

When you start by building the generic solution, you systematically make your life harder and often end-up updating your code to be less generic in the long run.

True reusability

Let's now imagine that you have to build a third website with some news on it. This time, the news are longer articles with images and videos in them. You can now look at the 3 websites and see what's the same in terms of UX and code. Chances are that the similarities are actually in the admin section; you want block of contents for all 3 websites. Not only this is truly reusable but it goes beyond the news sections, it's applicable to the pages and blog posts too. This is why light CMS such as FeinCMS exists...

Image Credits

Delusion - Water picture - by Sergey Lebedev via Free Images