6 + 1 Tips to Write Easily Extensible Code

As promised in the post The 0 Ohm Resistor, here there are some suggestions you may find useful while developing a new project. Following them will make your life easier when someone asks you to add some features in a short time.

If you apply these advices, as a side effect, you'll also help your colleagues to quickly understand your code and make changes autonomously.

1. Use Defines

This is a quite trivial suggestion but, believe me, I've seen numeric literals used in several programs. Every time you declare a fixed-size array or set a limit, you should create a define or a constant. In this way it will be faster to change it when requirements evolve.

Unfortunately, not every programming language supports defines or constants. In such cases, the best practice is to use variables with all uppercase names. Though it has not effect on the compiler, it should tell to your co-workers that the value of that variable won't change during the execution of the program.

2. Use Getters and Setters

For object oriented languages, it's not a good idea to directly expose members. Even for simple classes, it's preferable to have private members and public methods to read and write them.

The two main concepts here are implementation hiding and data encapsulation. The code outside your class doesn't need to know how you implemented a particular feature. In addition, in a function you can add other code (for example, a check on the new value for setters).

The thing that makes this tip future-proof is that you can change type and name of your members without impacting the rest of the code.

Just one note about Python, where @properties should be used. Basically they do the same things of getters and setters in a more elegant way. An exhaustive explanation on how Python @properties work can be found in this tutorial.

3. Write Small Functions that Do a Single Thing

There's nothing worse than having a function or a method one-thousand lines long. It's hard to understand and almost impossible to change it's behavior without rewriting it. With small functions it's easier to change some details or add something in the right place without being frightened of hidden side effects.

Corollary: unless a heavy optimization is needed, don't write code that is hard to understand for an average programmer. If you cannot avoid tricky code, remember to comment very well what it is supposed to do.

4. Prefer Text Files Where Possible

Unless you are working on systems with limited speed or storage, consider using text files to store configurations, logs and everything else. Binary structures are faster to read and write but every time you change the format, you need to update several parts of your code.

Another point for text files is that the debug is easier and, in case of troubles, an handmade change can save time and money.

5. Use Names Not Related to the Solution

It is easy to call a class ArrayValues, and it seems reasonable, too. But it's wrong. It's not just a problem of (lack of) implementation hiding. If tomorrow the array has to be changed in a hash table, what would you do? Keep an incorrect name or change it everywhere in your project?

The key point here is that the solution you have found to solve a problem may vary in the future, so it's better that names of variables, functions, classes, etc. reflect something that will never change: the problem to solve.

6. Avoid Code Duplication

Another trivial tip, don't you think? But you won't believe how many times I've seen two (or sometimes three) functions doing almost the same thing in the same project. The reason is simple, who added the second function didn't know (or didn't remember) that a task is already performed by a function already present.

In some cases it's the fear that makes someone say: "Maybe if I add this little feature I can add bugs to something that is working. No, it's better to create my own function". The result is that, for every subsequent change or bug fix, there is the risk to not consider every implication.

Bonus Tip - Do the Refactoring

This is something that is (hopefully) not necessary at first, but as the modifications start to accumulate, take some time to review the changes and harmonize them into the structure of your program.

In this way, in the future you can keep adding features on a structure that is stable and well implemented.

Image credits: Ladder by blickpixel licensed under CC0 1.0.

Post last updated on 2017/07/09.