Writing Clean Code Part 1 || What is Software Architecture and Design, and why do I care?

Greetings developer, I am glad you could stumble upon this post! Before we begin I must list the required skills before continuing into this series of posts about system design and architecture. To begin, I assume the reader has a solid understanding of OOP in lua, and, I assume the user understands what tables are, and their usage when creating data structures and implementing them with algorithms.

With this out of the way, let’s get into who I am. I am Samuel Taylor, at the time of writing this, I am a backend software engineer for Main Street Financial and a prior software engineer for Fetch Rewards. For those who are familiar with the Fetch app, I was responsible for refactoring the user profile service as well as its implementation in the new activity feed. I am also a 15-year ROBLOX vet with over 550 million contributive place visits across multiple games. Why am I saying this? Well, so the readers of this post can know this isn’t a “dude trust me” post. Now, let us get into system design and architecture.

What is the reason for this series?

As I have developed on this platform, the developers I work with struggle to write clean and well-structured code. And this series will help those developers which are willing, to understand and design clean and efficient code to easily update and expand games without the need for total refactoring or the “INSERT-GAME-NAME + VERSION-NUMBER” idea. So, the goal of this series is to attempt and remove the confusion and define what clean design and architecture are.

The word “architecture” in software engineering tends to indicate high-level concepts that are separate from lower-level details. These lower-level details are referred to as “design” implying we encapsulate the structures and decisions that happen at this level. But this usage is laughable when you look at what a real architect does.

Consider the architect who designed ROBLOX. The architecture in this case is simply how the platform is structured. The way that ROBLOX connects the studio to the website, the way that the user data is written and read. This includes every high-level detail and every low-level detail that could possibly be conceived in the development of this platform.

Do you think that the ROBLOX engineers, as frustrating as the platform is could be as successful as it is without well thought and planned system architecture and design? No, it is simply impossible. Don’t believe me? Well, consider this data from a real company which was mentioned in Robert C. Martins’s book about Clean Architecture.

The first Graph I will list will contain the growth of the engineering staff. Under ideal circumstances, this graph will appear to be very encouraging. More developers in theory mean more production!

image

Now, let’s look at this company’s supposed production that we theorized earlier.

image

There is a clear problem with these graphs. You may be thinking that they are labeled wrong. I wish this was the case. As the code grows, we appear to be reaching a production rate of 0. This rate is not sustainable long-term and will cost the company extra money to hire new engineers to try and fix these issues. Don’t believe me? Okay, let’s take a look at this next graph.

image

We keep hiring new engineers so we should have more productivity when in reality, we spend more and more money for less production. This will over time lead to the company going under and completely dissolving.

So, what went wrong?

We have heard the term slow and steady wins the race. The tortus and the hare story throws around the theme of foolishness and overconfidence. This is one of ment reasons why modern developers code in such a messy way. We are fast and messy, we code before we think, and we never go back to fix the problems we create. We come up with a solution and if it works we leave it for the next guy.

We do all this even though deep down as developers, we know what good code is, and we know what bad code is. But we still think the best way to develop something is to simply throw a project together for the sake of completing a it. This is done all while throwing around the phrase, “I will clean this up later” and “It’s good enough” and my personal favorite “ill fix it in the next project” when in fact we don’t have time for a later because we will be busy implementing new features. We should never settle with good enough, your O(n!) algorithm is inefficient and leads to memory leaks. And planning for a new project because of the way you designed a system is a foolish disposition we are all guilty of having. But we know all of these arguments lead to a jumbled mess of code and slowed down productivity. Slow and steady to win the race because the fact is, if we make a mess and have to clean it up, it will always be slower than doing it right the first time, and that is why this company had a problem.

Jason Gorman a Project Leader in the Microsystems and Nanotechnology Division within the Physical Measurement Laboratory at NIS. Knew this and ran an experiment using test driven development of TDD.

Here are the results:

image

Notice how the work is accomplished more swiftly on later days than it was on earlier days. Also, observe how the work moved forward 10% quicker on TDD days than it did on non-TDD days. It’s amazing how simple unit tests can speed up production.

Now you may have the question of, “what am I supposed to take away from this?” and this is a good question to have. The answer to this is simple, slow and steady wins the race, and don’t rush the development process. Know your domain before you attempt to write code for it. Avoid being overconfident and foolish. You don’t know everything, and you need to research the subject to write code efficiently.

With this, I got your attention. Software Design and Architecture is an art, a science, and an activity. It has been studied, experimented with, it’s been abused, and manipulated, and restructured for many years. But one thing remained through the test of time, clean code is happy code, and happy code means high productivity.

Please note you must also be aware of the personal flaws of system architecture that contribute to poor design in order to construct a system with a design and an architecture that minimize effort and enhance productivity. You need to study, I can only provide so much information, yes, I may have studied this for a while, but I have hundreds of hours of learning these concepts, I hope you strive for the same.

So, what is Software Architecture and Design, and why do I care? It’s the art of writing good code and you care because it’s the only way to write extendable, efficient, and clean systems.

30 Likes

Great post here, I actually learned something:

My codebase is very messy due to myself always trying to cram in as much time as possible. This post helped a lot, I want to start cleaning up the mess I made.

4 Likes

Glad I could help, I will make sure to tag you whenever I post part 2!

3 Likes

I can’t wait for part 2!

Just saying this would help a lot of people that throw things together that just ‘work’. Any tips on how to structure my codebase? It’s very messy as of now.

1 Like

For those who make it to the end, this will be a long series. I plan on covering every aspect of system design and architecture. How to compose functions, what is SOLID, ACID, CRUD, CAP Theorem, how to design highly scalable systems, design patterns, and everything else that goes with it.

4 Likes

I really like this post, a lot of Devs will find Thai useful, I only got to tell you that this goes in #resources:community-tutorials

3 Likes

Try and understand the problem that you are trying to solve. This is important to design systems that are scalable and clean.

Try and use modulation as much as possible, and use simple, not complex logic.

2 Likes

Oddly enough, I posted one of these in there, however, someone said to take it here, lol.

1 Like

That guy was wrong then, you are explaining, not giving a resource

1 Like

I think this fits in both, this is meant to be used as a resource on how to write code. It’s not really a tutorial per se. I am going to leave it here for the sake of it being a resource for the community as a whole.

3 Likes

Part two:

1 Like