How to write good software

Last updated: 2023-09-12

Comments on Mastodon

All posts: Index

It’s obvious that this isn’t a full how-to. There’s so much more to writing good software, but these the main points which I consider to be the most important ones.

Widely accepted tools and languages

Good software is written in a language that is widely used. That guarantees that there are people who can read and modify the code. Good languages, for example, are C, C# and Java. There are of course exceptions where less used language is a better choice.

Keep it simple

Good software doesn’t do things it doesn’t need to do. In other words, there aren’t unnecessary features. Implementing features that no one uses will only introduce bugs. Keeping things simple should be a top priority when designing software. Like Albert Einstein said, “Make things simple as possible, but not simpler.“

Too much abstraction is bad. If you hide the code behind multiple levels of abstraction, you will also hide the bugs. Too much abstraction makes the code hard to understand, makes it hard to follow the execution paths, and it makes it hard to debug. Often it will also decrease performance. Abstractions over abstractions are often a problem found in enterprise software written in Java. Good software can be written in Java, but Java also makes it quite easy to write code that is hard to understand. The same goes for C++.

Don’t make it rocket science

Use variable names that have a real meaning. Don’t use one character variable names. They’re almost impossible to understand and to keep track of. However, there are one character long variable names that are commonly accepted. For example, in coordinates, it is OK to use x and y. In for loops, it’s OK to use i, j and so on. Other than that, do not use them. In good software, the code is structured in a clean manner and there are documented coding conventions available.

Documentation is important

Despite how boring it might be, good software is documented. Code has comments that are meaningful, software has manual pages which are installed with the software. For web applications, make the documentation available online.

Often, developers think that it’s enough to write the documentation once the software is done. That’s a completely wrong approach. Documentation must be a thing developers do while they develop the software. Documentation is part of the development, not something you do after the code is written.

Use a version control system

Good software uses a version control system. Always. Nowadays, I will usually recommend Git for version control, but there are use cases where something like SVN does the job equally well. Version control makes it easy to roll back possibly problematic changes. Consider the following example, what could (and will) happen without a version control system:

Developer A makes a change in a file program.c. The file program is copied over to the source tree and the old file is replaced. Later, a bug is found that originates in the change’s developer A made for the file program.c. Developer B, C etc. will have hard time finding out what was the change developer A made.

With a version control system, this would not be a problem. Developer B could easily see what the change causing the bug was.

Extensibility

Extensibility is not strictly a requirement, but often it makes the software more useful. One good approach is to develop the software so that it’s modular.