DEV Community: detoix

How many Harry Potters can your team maintain?

detoix — Tue, 24 Oct 2023 21:04:49 +0000

Talking to the business is hard. Convincing them that your application requires time for refactoring or maintenance is even harder. I've been there and I want to share with you an interesting metric that bridges business people and engineers.

A couple of months ago I was assigned with a task to explain why we need time for refactoring, why can't we just remove the code we don't need. And it was a struggle because I didn't know how to quantify the system we had. How do I tell the business people how much cognitive effort we put into just understanding what's under the hood of a running system?

And I came up with an idea to compare it to a book. Simple as that: every line of code takes time to read and understand, just as every line of a book.

How much is a Harry Potter?

I chose Harry Potter series because it's well-known (eventually it turned out to be the bull's eye). I found a couple of places like this that claim that

the Harry Potter books contain 1,084,170 words

Yeah, maybe. My concern was to find out lines count.

Why lines?

A line of code is an entity a developer works with in the first place. Also, it is easy to imagine a line of written text. My assumption here is that every word somewhat corresponds with a single token in code (variable, assignment, invocation), because it represents a single thing to understand in the bigger context.

So I decided to find out myself how many lines are there in the Harry Potter books. And the results are as follows.

Title	Word count	Line count
Harry Potter and the Philosopher's Stone	76,944	7,890
Harry Potter and the Chamber of Secrets	85,141	8,695
Harry Potter and the Prisoner of Azkaban	107,253	11,190
Harry Potter and the Goblet of Fire	190,637	19,077
Harry Potter and the Order of the Phoenix	257,045	23,004
Harry Potter and the Half-Blood Prince	168,923	13,454
Harry Potter and the Deathly Hallows	198,227	20,630
Total	1,084,170	103,940

I did some double checks and confirmed these numbers - 100k lines in the whole series. Now, how does it compare to actual code? I used some of my onliners to get some data about popular repositories.

Title	Token count	Line count
Autofac	152,249	42,137
three.js	1,614,528	272,856
pandas	1,804,215	457,886
Total	3,570,992	772,879

As you can easily notice, the ratios are much different. Whereas in a typical novel there are about ten words per line, in the code I pulled there is less than 5 tokens per line.

These two numbers are difficult to compare, but I would argue that software code requires significantly more cognitive effort to be understood. Remember that we're doing this to establish some common ground between business and software people, these numbers don't have to be equal.

This is the part where you can disagree, but for the sake of simplicity of calculations I claim the following.

1 Harry Potter ~ 100k lines of code

With this in mind I literally put it on a Power Point slide and said that

we currently maintain an equivalent of X Harry Potter series with a team of Y engineers and that's why we have to simplify the system

and I think i made a point. If you're reading this for the first time and this idea is fresh in your mind, try to imagine being a business professional and learning this from a software engineer. Is it intelligible? Does it help you understand the situation?

Such comparisons, the Harry Potter Metric in particular, can be a novel approach to bridging the gap between business professionals and engineers; it's simple to calculate and easy to understand for both parties.

So, how many Harry Potters can your team maintain?

SRP for couples

detoix — Sun, 03 Jan 2021 15:09:29 +0000

Single Responsibility Principle is a well-recognized rule that all software developers (and, as you're going to see, others as well) should follow in order to make systems maintainable and easy to extend.

There are many definitions and ways to explain it. Here I'd like to lay out what I believe to be a comprehensive real-world explanation of how should this principle be applied. And to do that, we're going to visit a couple's bedroom.

Bedroom drawers

When two people live with each other, in their bedroom, there usually are drawers with underwear. And there is not one, but two of them. It's common sense, but let's spend some time to find out why is it so. Why are there 2 separate drawers and, particularly, why is their responsibility split like that?

Other setups

Let's ponder for a while and imagine that you're moving in with someone, and you need to find out how where to put your socks and underwear. Some of the possibilities are as follows:

Socks in one drawer, underwear in the other one
White in one drawer, colored in the other one
His in one drawer, hers in the other one

Problem setting

What we generally want to achieve when developing a working (software) system is loose coupling. In our example, we expect a solution that allows for maximum independence of both partners, so it is not acceptable that one person waits until the other one dresses up.

If we, for instance, split responsibilities with the second solution we've listed above, out actors will encounter a problem when one of them will look for white socks, whereas the other one will be waiting for their turn to pick theirs.

The principle

The only way to prove one solution better than other is to follow the Single Responsibility Principle, which states that "an entity should have only one reason to change".

This reason is that a person wants to get dressed. Putting both partners' socks in one drawer and underwear in the other one causes that for any drawer there are two reasons to change - it is that any of two partners wants to get something and it leads to obvious problems.

Conclusion

Design your systems like bedroom drawers: let your code areas change independently by different reasons and you will find out that it is nothing more than the same common sense that leads to putting underwear in bedroom drawings in this well-known way.

3 ways to use boolean in a bad way

detoix — Fri, 24 Apr 2020 15:41:37 +0000

1. Carry checkbox up to your high-level code

Every application is a sort of data processing. As such, in order to provide output, it requires some input. More often than not it’s a so-called “user input” and among user interfaces there happen to be checkboxes.

A checkbox indicate that some option is enabled or disabled and, as such, is a valuable way of controlling application flow. But a developer’s job is to put code into layers and split the ugly low-level code from the pure object-oriented (or functional) high-level code.

Unfortunately, we often fail and as we receive the checkbox value in a form of isPremium, isValid or isAuthorized, we tend to pass this argument deep into the application.

It should never be like this, because the more objects or functions know about isPremium or similar, the more conditional statements will appear to handle this information.

And the solution is to convert the raw input data as soon as possible into a high-level domain code with objects, higher-order functions and so on.

2. Use boolean to indicate objects interaction

Dealing with object-to-object interactions within a video game is an incredibly difficult process. So we have a character which is able co crunch when there’s not enough space to walk. How would you introduce such a feature?

Do you think that the character can check for isSomethingAbove and depending on that flag switch to crunching? Of course not, the character should be responsible for its actions, there should be some communication between character and its environment!

Such a model appears mostly when the developer does not expect much behavior from some minor thing. Here for example we may have a low ceiling that makes our character crunch. As the sole responsibility of the ceiling is to change the way the character moves, one may avoid to introduce a separate entity for it. But it's wrong! Even a single behavior is enough to delegate this responsibility for a separate entity!

3. Expose boolean in an API

Let’s assume you have a code where you need to compare two objects by their nature. For example, your application deals with door-to-door deliveries, you have to compare addresses for equality and expose areEqual to some sort of API.

Looks good, but remember that a boolean can only provide true or false! So there comes a business request to change the conditions for equality, but you still can expose only true or false. Can you see the problem?

The problem is that as you have exposed a boolean you cannot tell everyone that it is no longer valid! Maybe someone depends on it and will never know that a "new false" is a different "false".

If you need to expose raw data in such a form, always use some sort of nullable or enum to make sure you can easily make the field obsolete to tell everyone they can no longer count on it as they did before.