The state of a modern repo

Marcus Christensen — Wed, 11 Aug 2021 14:01:03 +0000

Background

During the years I have seen many tools and technologies both rise and fall, both good and bad attempts on solving different problems in and around development.

In my early years source control wasn't even a thing, issues was tracked by pen and paper and a release was something that you as a developer created on your own machine. :P

Much time has passed since then, and looking back at this, it's easy to see that we are in a much better place today, with modern tools and services like GitHub, that offers a complete package for what you need.

The problem

With the advent of toolchains and build pipelines, among other things, we have had a need to save configuration for a lot of stuff along with the actual code in our repos.

On the whole, I think this a good thing, as the possibility to discuss and change configuration, along with what tools to use is much more in the open nowadays.

But, what I dislike is that the root of a repo is a free-for-all to save configuration files in.

Just take a small peek into the Forem repo for dev.to, to get a hint of what i mean.

Along with the few folders of actual code, there are countless of files and folders needed for the different tools used for testing / building / deploying.

Disclaimer

Take note! There is no blame sent in the direction of the
Forem team, this problem is visible in almost all repos, in some sort or the other.

Question

What if I happen to be a new coder, eager to test out opensource development for a project i really like?

In my line of work as a professional developer, I often come back to the fact that we manage complexity, and try to present it a something simple.

Not to hide the complexity away for everyone, but instead not to scare away the people that just want to get a grasp of what the system does, and be able to dive into the details when ready.

I just feel that we could do better in some areas when it comes to all the configuration-files as well, can't we?

Happy coding! :)

Abstractions offers readability

Marcus Christensen — Wed, 11 Aug 2021 13:35:47 +0000

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! :)

DEV Community: Marcus Christensen

The state of a modern repo

Background

The problem

Disclaimer

Question

Abstractions offers readability

The problem

Abstractions?

Methods

An example

Oh no, this is my reality!

How to fix it?

Where to stop?