Evolution and documentation

This month's post is a reflection on the human nature and poorly written codes

Summer finally arrived in the Netherlands with a pretty hot weather even for my Brazilian standards, and I have thankfully been able to spend more and more time outside and even get some color (which in my case means “slightly less white”). I even went camping on a few days off, which was great to start exploring the country now that we have an ever-healthier environment. The best thing to do when chilling in the sun for me is to grab a good book, and this is how I came across a very famous one: Sapiens, by Yuval Harari.

I have just begun it, but I am fascinated by the way the author tells the history of mankind, even before history itself. One of the most interesting aspects of it is what he calls “cultural revolution”, when the human beings started to create abstract concepts and pass the knowledge on to the next generations, allowing a much more pronounced development of the species. I started to observe how this basic ability is connected to the things in my life, and probably Science is one of the aspects that mostly depend on it.

This was my humble setup for exploring the north of Limburg!

In our everyday lab work, we constantly apply concepts that have been developed over the past 6 centuries without even thinking about it. And the systematic way in which this knowledge is passed on is essential for new discoveries to be made. However, I also noticed that in my daily work there is an aspect of this knowledge transmission that is often overlooked: documentation of software.

We, engineers and programmers, spend a lot of time writing clever codes that will extract information from the available signals, and many papers have been published on such algorithms and their outputs. But anyone who tried to use code previously developed by other people, unless structured in a complete software, knows the nightmare it can be to try to untangle them.

And even though we usually try to use clear variable names and to comment the code, this is sometimes also not as useful as we would hope, and a document explaining how it works would be incredibly beneficial to make it usable in the future. This is important not only to make our personal researches more relevant, but also to speed up the progress of science itself.

There are thankfully many tools that help coders to make their work more understandable, things such as the git structure and well written readme files. I have been trying to incorporate better documentation strategies in my codes, with help functions and detailed explanations of the input arguments. Hopefully, they can be used by everyone in the future!

I have been working a lot in programming new tools for my work in PersonalizeAF, and I am finally approaching a point where I can share some nice results and thoughts on atrial fibrillation. But there still a way to go, so I will leave that for a future post! Meanwhile you can check posts by the other ESRs, for example here and here, and follow us in the social media and Youtube. See you next time!