Thorough documentation of source code (in other words a solar flare can't stop Dactyl)

It all started with a solar flare. It triggered a powerful electromagnetic wave that traveled across the universe to a chip located on our server board in Dactyl. A bug has appeared... Where's the documentation?

Even a solar flare won't upset us

*beep* What's that sound?

Oh, no! The wave has manipulated our chip and completely re-prioritized it. It mixed priorities so much that it suddenly decided to report an error message...

„500 Internal Server Error!”

...and always only for a specific query.

"What's going on? This doesn't happen to us at all!" rang out through our office.

And no wonder. All our servers have a stable Linux operating system. They run in constant operation (even when the operating system itself is updated).

"How is it possible that the error has appeared now? This can't be a coincidence," thought our web developer Štěpán.

Such a problem is not solved by restarting the server service while we go for a hot coffee to recharge our batteries. No, it's necessary to act fast and fix the bug directly in the source code! 

So our search can begin.

Next comes debugging

A bug report is coming from the leadership with an attached description of how to reproduce it. But Stepan is already one step ahead and so he wonders what could have caused the error. It's not that difficult to track down the actual breakpoint and find out where the fault is occurring. 

Smart tools make the search easier. We can look at error messages with the help of logs or analyze the code step by step.

The problem can be compared to a badly assembled cabinet. We are not exactly experts in furniture assembly, so we always get advice from a professional on where to tighten which screws.

Our expert advisor this time is the debugging software Xdebug.

We can get started... but wait, where's the manual?

Salvation is brought by thorough documentation of the code

Why waste time reinventing the wheel, especially when such a wheel has thousands of lines of source code. Most of the time it is a colleague's or third party's source code. We have everything ready, nicely put together and we don't have to waste energy. 

We are talking about so-called libraries. However, the occurrence of errors in libraries is not at all common and is most often related to incorrect usage. 

But back to our problem. We still need to find out exactly where it went wrong. So we need to break down how the whole thing works, understand it, analyze it, and then adjust it.

It brings us to an integral part of writing source code, and that is documentation.

Any function that is not completely trivial, intuitive and we cannot figure out at a glance should have a verbal description. Then the programmer does not have to struggle with it and can quickly find his way around the specific environment... where we are looking for the bug!

Oh! Finally, we see what's wrong.

We found the problem. So we can start figuring out how to fix the bug or how to change the functionality to fit our desired scenario. The source code documentation will help us with this.

It's one thing to write code but to understand in that?

But writing quality documentation is no fun. It is important that the result is nicely coherent. We can imagine a cookbook, for example, in which we find great and well-described recipes. But one is from my grandmother, one is for Asian delicacies and one is from a Michelin-starred chef. 

Such a cookbook lacks integrity and it is difficult to make sense of it, let alone look for something specific in it.

Similarly, the source code must have a structure. However, each programmer has his own handwriting and writes code differently. Unless a robot writes for us, we have no chance of ever unifying such code. To make writing and then reading easier, it's a good idea to stick to conventions. There are several ways of writing, and it is up to each programmer to choose which one.

Let's do it again on our favorite cookbook.

In a recipe, we usually find the same structure - it starts with the ingredients, the quantity needed and then follows the cooking procedure. The process itself is described in detail and must not be missing, for example, if and how the food needs to be cooked, in which device, for how long, at how many degrees and so on.

The reader is always aware of which part he is in. He can thus easily compare different recipes and knows at a glance where to look for the necessary information. 

And the same is true in the world of programming. We can't burn the source code, but we can still make mistakes by mishandling it. So the convention ultimately serves the programmer to realize the error and then easily correct it by changing variables.

After a thorough check, straight to the finish

What guarantees well-written documentation? 

First of all, it is the programmer himself. Don't think, maintaining documentation and a good source code structure takes time. That doesn't mean we can't help ourselves. At Dactyl, we partially automate this step with the help of appropriate tools.

But it's always best to get verification from a colleague. Newly added code segments go through production review, so that takes care of that. Programmers often don't even work on the same product, and that's a good thing. More eyes can see more and we'll know right away if our code is really understandable.

And if we accidentally miss something, PHPStan will help us. This helps us to keep an eye on the correctness of the code but also to eliminate bugs and relieve the hardware of unnecessary load.

Don't be afraid of good criticism, through it we can pass on valuable experience. 

Mission complete. The problem was found and effectively eliminated using teamwork and modern technology. Now the only thing left to do is the last thing...

And the last thing?

Oh, no we'll never get any rest. What happened, you ask? There's always something to tweak, extend and fix... because debugging code is a continuous process. Anyway, back to work!

Have you had an issue and a restart didn't help? Are solar flares preventing you from developing a supermodern app? Contact us, we'll handle it for you!

This article was prepared by Štěpán Kubičný, our PHP developer.