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

Creating and Publishing an NPM Package with Automated Versioning and Deployment

In this step-by-step guide, we’ll create, publish, and manage an NPM package using TypeScript for better code readability and scalability. We’ll write test cases with Jest and automate our NPM package versioning and publishing process using Changesets and GitHub Actions.

Read more

Offloading File Transfers with Amazon S3 Presigned URLs in Spring Boot

When building web applications that involve file uploads or downloads, a common approach is to have the files pass through an application server.

Read more

One Stop Guide to Java Functional Interfaces

Introduction to Functional Programming Functional programming is a paradigm that focuses on the use of functions to create clear and concise code.

Read more