Start Clean!

Start Clean!

Table Of Contents

As software developers, we’re painfully aware of technical debt.

Usually, we curse our predecessors for taking shortcuts, making wrong decisions, and for just not working professionally in general.

That’s unfair, of course. Whoever wrote a piece of code that is technical debt in our eyes had to work with the knowledge and in the constraints of the time when they wrote that code. There probably were time constraints and technical constraints (among other constraints) that we have collectively forgotten about today.

But still, when we get the chance to start a new codebase or a new module within a codebase, we say to ourselves that we’re going to do it better. We’re going to build something that our successors will praise us for. We even proudly put our name in the header of the source files!

But then the constraints hit us. People start asking us when it’s done. The API we’re using turns out to suck and we need to build workarounds.

That’s life. We can’t control everything. But that’s not a reason to give up on the things that we can control.

When we start something new, we have a responsibility to make things as good as we can, within the constraints that we can’t control. If we skimp on the things that we can control, our successors are right to accuse us of being unprofessional.

Here are some things that we can usually control when starting a new project.

Document Decisions

With every decision, think about whether this decision is an important information for the developer you’re going to hand over to at some point. Does it provide context? Does it explain something that would otherwise surprise a new developer? If in doubt, document the decision.

Explain the high-level architecture

There are few things as frustrating as sitting in front of an unfamiliar codebase and not having a clue what the code is about. This is very easily fixed by providing a high-level architecture overview in a README file. A simple boxes and arrows diagram does wonders for understanding! And it doesn’t have to be very detailed, so it’s easy to keep up-to-date!

Structure the code into modules

When you’re starting a fresh codebase, even if it’s just a few sourcecode files, yet, split the code into modules or packages. This will make your life easier to understand the code and it will make it so much easier for the next person to understand it. Having clear modules from the start will make it easier to draw a high-level architecture diagram, making it even easier to understand for newcomers.

Leave a README in the code repository

As mentioned above, a README can contain a high-level architecture diagram. But it can also contain instructions how to set up the local developer environment and any tips and tricks on how to deal with the codebase. Open source projects usually do a good job of providing a README because many people without much context are working on the code. Why should a README be exclusive to open source? It will help just as much (or even more) in internal codebases where people are working on the code every day.

Polish the code

Once you’re done with the initial design of a new codebase, make a polishing pass over it. Now is the time that you still have the context of project and you can make improvements. There will never be a better time to do this. If you don’t do this, you will open up the codebase to instant pollution because other developers will add code in the same style as the code that is there already. Every line of code we’re creating is legacy code for the next developer. Take the time and review your own code after a day or two and ask yourself what you would want the code to look like if you had to work on it a year from now.

Good Conscience

Doing these things, chances are that your successors will still curse you for the things that you didn’t have control over, but at least you can sleep at night, knowing you did everything within your control to make things as good as they can be.

Written By:

Tom Hombergs

Written By:

Tom Hombergs

As a professional software engineer, consultant, architect, general problem solver, I've been practicing the software craft for more than fifteen years and I'm still learning something new every day. I love sharing the things I learned, so you (and future me) can get a head start. That's why I founded

Recent Posts

Understanding Socket.IO: Building a simple real-time chat app with Node.js and Socket.IO

Traditional web applications primarily used the HTTP request-response model, where clients sent requests to servers, and servers responded with data. However, implementing real-time features like live chat, notifications, collaborative tools, etc, was challenging.

Read more

Spring Basics

At its core, Spring is a Dependency Injection framework. Although it now offers a variety of other features that simplify developers' lives, most of these are built on top of the Dependency Injection framework.

Read more

Spring Boot Basics

Spring Boot builds on top of the Spring Framework and provides a wealth of additional features and integrations. To simplify somewhat, one could say that the Spring Framework focuses on functions related to the application context, while Spring Boot provides functions that are needed in many applications running in production or that simplify developer life.

Read more