Basic rules

Here are a few basic rules for creating maintainable code.

Don't try to do everything at once

If you find a bug in your code, the first job is to fix the bug. Fix the bug and test it to make sure it works. This is the prototype stage - it doesn't matter if the code doesn't look quite perfect so long as it works.

Once the bug is fixed, you can look at your code and check if it needs any improvements to make the code more maintainable. This is the code review stage. Think about the different areas that are important for maintainability - comments, indentation, variable names etc. Then test again to make sure everything still works.

You can't do everything in one go. While you are fixing the bug, the code might get a little bit messy, but you can always fix it later.

The same applies if you want to add new functionality to your code. Prototype the changes, get everything working, then review the code and tidy things up.

Code is written once but read many times

You only have to write a piece of code once, it is worth spending a little bit if time making sure it is well commented and maintainable. This is the one time you really understand how the code works, and why you wrote it the way you did.

If you (or someone else) has to change the code in the future, after you have forgotten even writing it, all you will have to go on is the code itself. Do your future self a favour and make sure you make the code as easy to understand as possible.

The DRY principle

DRY stands for Don't Repeat Yourself and it is a very important principle is software development.

Consider this loop:

print('What is the capital of France?')
answer = input()
while answer != 'Paris':
    print('What is the capital of France?')
    answer = input()
print('Correct')

These lines appear twice in the code:

print('What is the capital of France?')
answer = input()

Why is this a problem? Suppose you wanted to change the question to "What is the capital of Italy?". To someone who isn't familiar with the code, it would be easy to make a mistake and just alter the question the first time it appears in the code, but forget to change the second appearance. The code is less maintainable because it contains a trap, which could cause a bug further down the line.

In this case, the best way to avoid repeated code is to restructure it to use a flag, like this:

while True:
    print('What is the capital of France?')
    answer = input()
    if answer == 'Paris':
        break
print('Correct')

In this case, the while loop carries on forever. If the user gives a correct answer, a break statement is executed, which jumps out of the loop.

In other cases where you find a block of code is being used in several places, you might consider converting it into a function.

The YAGNI principle

YAGNI stands for You Aren't Gonna Need It.

Suppose you are writing a program to store students' test scores. Part of the program requires you to print out a list the names and scores of all the students, ordered according to each student's surname.

While you are writing the program, you think that it might also be useful to write an extra function which lists the names and names of all the students, but ordered by score rather than name.

Nobody has asked you to write that code, nobody has said they might need it, but you think you might as well write it anyway, just in case.

That is where YAGNI comes in - don't write that extra code because You Aren't Gonna Need It.

In reality, when people start using your program, they will probably ask for new features which you never even though of. Most of the things you thought might be needed aren't needed at all.

It isn't just the time you spend writing that extra function. Every time the program gets updated, someone has to look at the function and decide if it needs to be modified. That is extra work for a function which nobody asked for and isn't even being used.

And if someone does ask for the results to be printed in order of score, you can just write the extra code then.

See also

• Writing code
• Malicious attacks
• Security concepts
• Motives
• Exploits and defences
• Example - SQL injection
• Maintainable code
• Comments and layout
• Naming items
• Globals and side effects
• Change control