Hello, developer. I’m glad you got this far, by chance of fate, maybe. I want to start a move, the “CodeDoc” movement to document source code correctly and make the code healthier. And I’d like you to join it.
First of all I want to make one thing clear: here I will present a guide that, to this day (January 2021), is a personal opinion. I don’t mean to sit chair, but I do think my approach can help other developers.
Like almost everything in this life, there are more ways to understand things besides the one you have. That said, this is my vision of a topic that, because of my long experience in the sector (25 years to date of publishing this), remains the great forgotten of the developers, especially the younger ones. If you want to contribute your ideas, contact me and we will discuss them to add them.
“Based on evidence”
Well, based on my evidence. 25 years of professional programming give for many experiences and, after these years, it is clear that something I have learned: documenting the code is essential. Yes, I don’t say interesting, nor do I say important, I say fundamental. Every year new generations arrive and I still see the same thing now as 20 years ago: a hundred lines of code and one or two irrelevant comments. That’s not maintainable. We must habituate the new generations to document right. Spread the movement!
The developers, those strange beings
We are passionate, we are intelligent, we are curious, but what we are not is prone to detailed explanations. We have a hard time documenting, it’s a reality. Just open any GitHub project and you’ll see that the comments in the code shine through its absence and that the main documentation is usually, at best, short. There are clear exceptions, but that’s it, exceptions.
It’s time for us to change that. No matter if you are a lone wolf or participating in projects with dozens of colleagues, documenting (or if you prefer the term, commenting) the small pieces of code that do wonders is essential for the future maintenance of that project.
Because what you just did today and it has taken you two hours to solve for its complexity, which you have then refactored and in the end has stayed in ten beautiful and powerful lines of code, you remember that perfectly tomorrow, next week and next month. But a year later you’ll need to modify the design and you won’t know why you did it like this. What’s more, you won’t even know what those extravagant solutions you applied do and you’ll have to step-by-step analyze what that advanced ten-line design does. And you’ll spend 15 or 30 minutes trying to understand what you did. And, that’s when you’ll realize you should have documented this, so you don’t have to waste time now.
And that’s if you did the code. Now imagine what will happen when someone else picks up your code (or you pick up someone else’s) and spends 30 or 60 minutes analyzing which machiavellian mind designed such a solution in just ten lines of code.
Documenting is easy, if you know how to do it
In the following chapters I will give you the keys to document your code effectively. I’ll show you real examples (source code in production) of correctly commented code and examples of the opposite. It is the same solution that I have been applying for 24 years with total success (yes, the first year I did not document either, until I understood its importance). I can tell you, for example, that the companies I developed custom software to in 1998 continue, to this day, to use my programs and request changes and improvements. And if I’m able to do them quickly and without breaking anything, it’s simply because everything, absolutely all my code, is commented out.
Documenting is automatic, if you incorporate it into your routine
We’re having a hard time getting started, yes. But we are beings of habit. It’s like moving from one language whose statements just end up (like Python) to another in which they have to end up in “;” (such as Java). At first you find it hard to get used to it, but repetition makes it incorporate into the way you work automatically, without you nodding.
I’m not even thinking I’m commenting on the code. As soon as I finish a somewhat complex block of code to understand, I’m automatically writing the comments. I’m putting my “;” to finish “the line.”
I invite you to come up with the movement and find out how to document your code correctly and when not to. Read the following brief chapters.