Abstractions offers readability

The problem

When you as an aspiring new programmer start your journey, there are a lot of things to learn, some of it is really easy to grasp while other things might be a bit tricker.

One of those things are abstractions, which is a horrid word and it makes even me flinch sometimes, so I like to turn it around and look at it from a usage perspective.

Abstractions?

Abstractions come in many forms, often it's used on a larger scale, like between parts of a large system.

Abstraction

So abstraction is used to let someone grasp the concept of something, without being exposed to the details, which is great, therefore I conclude:

Abstractions offers the reader readability.

Methods

So today I'd like to talk to you about abstractions in the small, that is sorely underused in many codebases, more specifically: methods.

We as programmers divide our programs into methods/functions to do certain things for us, we often do this based on possible reuse of logic.

But we often miss the opportunity to also simplify the code for the readers, by breaking apart blocks of code further, even though it's not needed for reusability, only for readability & simplicity.

So, (well-named) methods allows the reader of the code to grasp WHAT is happening instead of HOW that is done, and therefore offers simplicity in the form of hiding the details.

An example

Say that you need to fix a formatting error in an email that is sent with a weekly report to your customers, as help in the ticket there is a mention of the SendReport() method.

You search for the method, open the file and are faced with one 3500-line long method, that does everything...

Due to the fact that multiple people has been involved in adding features and fixing hard-to-find bugs in this code the last couple of years, it's all intertwined.

Were would you start looking?

You really need to sit down and read all of the code to find what you are looking for, and to see how to change parts of it, hopefully without breaking something else, which has occurred multiple times in the past.

If instead your SendReports() method looked like this, would you have an easier time finding what you're looking for?

You didn't have to look at all the db-calls that needed to be done to calculate the report, neither the specifics of how the email was sent to the client.

/// Send weekly report to all customers
function SendReports() {
  for(every customer in allCustomers) {
    report = createReport(customer);
    email = createEmail(customer, report);
    sendEmail(email);
  }
}

And then, even though your createEmail() function wasn't used from anywhere else in your system, it was further broken up into, let's say:

/// Creates a personalized email to the customer recipient,
/// and attaches the report.
function createEmail(customer, report) {
   email = new Email();
   email.headers = createEmailHeaders(customer);
   email.body    = createEmailBody(customer);
   email.attachments.add(report);
   return email;
}

It would be so much easier to find the relevant parts that you are interested in at the moment.

Oh no, this is my reality!

If you find yourself looking at the above example and thinking about the countless of similar files in your own codebase, I feel sorry for you, but I can also tell you that you are far from alone.

Many of us are working in older systems, which tend to have some amount of code like this.

How to fix it?

If you don't know how to proceed, a good rule of thumb is to try to leave the code in a slightly better state than you found it it.

So, when faced with an issue, try to break out just a tiny portion of the code, if possible, when fixing the issue, to make it easier the next time around.

Tests do help a lot when doing this kind of work, but that is another topic for another day. :)

Where to stop?

Well, it depends on your own decisions and what you find simple, but a good rule of thumb is that a function should do the least amount of work possible, and do it well.

Think about the next person that needs to fix a bug in your codebase, keep it as simple as possible for them to find the correct place, it might as well be you!

Happy coding! :)