There are several stages of maintainable code, each suitable for a particular situation. Let us call each stage a maintainability level. The higher the level, the more maintainable code is, and the more time it takes to write in this way. Do you always need the best possible maintainability?

For example, you are the only contributor for the code in question. You probably do not care much if someone else cannot maintain it. But you should probably be able to maintain it in 6 months from now. Unless it is some single use throwaway code you wrote in a few hours. At that point the code may be superseded by a 3rd party tool or otherwise be made unnecessary anyway.

If you do need to make it maintainable by others, how high should you go? First, we need to consider which types of developers will be maintaining our code. Perhaps, oversimplified, I defined 2 types of developers - Junior and Senior. Throwing in other titles such as Mid, Mid-Senior, Architect and so on will only complicate the idea I am trying to present, so we will keep those aside for now.

• Junior Developer

  For the purpose of this article I will define junior developer as a programmer of exceptional ability without prior experience. Typically but not necessarily a fresh grad out of technical college (math, computer science, engineering).

• Exceptional Programming Ability

  Being able to write a simple 10-20 lines of code that compiles, and runs without errors on the first try, or in 5-10 minutes. Without use of google or stack overflow.

• Senior Developer

  Senior Developer is someone with 10+ years of experience with or without exceptional programming ability. With experience ability matters less.

This way I defined a binary scale, it is approximate and you might fit a few interim values in between some of those, but let me get to the point. Say the code can be maintainable by the following entities, and it would progressively more time to produce:

• current self (quick and dirty code, but it works)
• future self in 6+ months
• most senior developers (typical enterprise development)
• all senior developers (big companies with 5 stage interviews and 6 figure salaries)
• junior developers in short term
• junior developers in long term (highest quality code)

On this scale it is important to mention that most enterprise codebases are following a standard to be maintainable by the majority of senior developers. An important distinction is that they are not necessary maintainable, it is just a standard everybody tries to follow. During rush time it may turn that code below this standard is produced and tech debt piles up. Which brings me to the next point.

You are trying to prepare your code for rush time, where your typical standard cannot be maintained, and how you have to downgrade. How far into the safe zone do you need to define your “typical” standard? The highest grade code on my above scale is “maintainable by junior developers in the long term”. I already defined “junior”. Long term means that given a few years of time, the application will continue to be functional and useful for business if only maintained by junior developers. So that means senior developers are off to another project, for example.

Put otherwise, can you completely remove senior developers from the project and be sure it will not collapse over time? Then you have high quality code. Alright, how do we get there?

Do not repeat yourself (DRY)

Avoid copy paste as much as possible. Every copy paste means there is some sort of technical debt in the application. If you find yourself copy pasting all day, try to find a better way of doing things. Most bugs come from developers who prefer copy/paste over any other approach. If copy/paste if your default action, you are unlikely to produce quality code.

Avoid god objects

God object is such that is trying to do everything. A typical anti-pattern is when a single 1000 line god object feeds 10 smaller objects each 100 lines long. While you might not necessarily see anything odd here, 95% of bugs will come from those 1000 lines. God objects are nearly impossible to unit test due to complexity.

If something causes a headache, developers will naturally avoid it. So it will never get fixed. Instead, consumer components using god objects will have workarounds everywhere. This exponentially increases size of code on the project.

Proper code is simple at every level. So all of your classes are 100 lines, for example.

You can find more explanation via other links on google if you follow “god object” keyword search.

Write simple code

Hopefully you have seen this picture below or heard jokes about it.

If your situation is the one on the right, your code is not simple enough. It may be simple in that you can understand it, and change it when necessary, assuming you have had enough sleep and a good meal. What if you only had 3 hours of sleep and skipped lunch - can you still be productive on that same codebase? Sleep and meal are just simple examples, there could be other events in your life adding stress to your workday.

Writing production code on a high quality codebase should be obvious and exactly zero stress activity. You write code how it would make sense and it just works. Or it almost works, and the IDE or compiler or the interface of the application tells you what to do to fix it. You only use your brain on architecture type code, but it is still obvious where things need to be fixed. If it is not obvious - you are either in a situation on the right, or getting there.