Magic In Code

Every developer faced a situation when he wrote a piece of code that works inexplicably. It is magic! — he says. But why a developer think that this is magic and not a consequence of some internal processes execution? And what should he do with this magic?

Why Magic?

Every piece of written code, no matter the language, is a command or a declaration that tells the computer to perform some actions. When a developer writes it, he should have a general idea of how it works under the bonnet and what it may cause. However, in some situations, this link between the action and the consequence is missing. It is what a developer call magic!

But why it happens? Why can a developer with an analytic brain and technical mindset not understand the internal processes and predict the results? There are several reasons for that.

First and foremost, it is complexity. Every software application, even the one that prints Hello world, interacts with the multiple layers of computer architecture. It is an application framework, programming language compiler or interpreter, virtual machine that converts written line to bytecode, operational system that executes machine codes and transfers them to hardware, and finally the hardware itself that processes them and returns the result. Each of these layers has its internal logic, and only an extremely experienced person knows how it works. Most of the developers are satisfied with only one or two highest layers, and surprisingly it is enough in most cases. But what if a developer does not know even the first layer?

Here we are going to the best and the worst of a developer's traits — laziness. It is good because it motivates to automate routine processes and saves time. But at the same time, it is bad because it prevents a developer from learning how the software environment works. The second example is especially bad in case of software that may endanger people's lives, like airplane firmware or nuclear reactor operation procedures. So, every reasonable developer must avoid such (and less dangerous) situations at all costs.

How To Avoid?

The obvious solution is to learn the software environment at least for one layer down. A developer should know not only how the code works but also what kind of calls application performs on lower levels to be able to predict consequences. Need also to remember that code can work differently in a different environment (local, dev, production), so a developer has to know the basic structure of all of them.

As for the complexity, a developer should avoid over-complicated solutions as much as possible. This recommendation is valid not only for the used components but also for the written code itself. After several years of active development, any code may become a mess, so that magic may happen there as well.

Another best practice is to work only with public and well-documented interfaces. By doing that, a developer can guarantee that code can work in different environments. Also, it is a good idea to describe and document all used public interfaces to understand all entry points. This approach also simplifies automated testing as it is easy to see what data a developer has to pass to test the code.

Magician View

Software developers who write the lower levels (software frameworks, compilers) should care about the magic in code as well. It is even harder, as they have not only to deal with the complexity of lower levels. Developers also have to write a code that does not look like magic to potential users from the higher level.

The best practices here are mostly the same as for regular developers. Clear interfaces, functional architecture, and proper documentation become even more crucial here as many developers are going to use this code. Developers have to know architectural best practices (KISS, YAGNI, SOLID, GRASP) and use them wisely.

Finally, these developers should be aware of the common use cases and do their best to implement them (or at least public interfaces to them) in the simplest possible way. Such an approach may save not only the time required to understand how the code works but also reduce the total number of issues and build an active community.

I hope these recommendations can help developers to write better and cleaner code. And when some magic appears, they should not leave it as is. Instead, they should learn how magic works, reveal it to everybody, and do their best to prevent this magic trick in the future.