Documenting code is an art or just a simple routine? I was and I am, always listening to the same old story. They don’t give us enough time for documentation. We are too busy to document the code. This is a convenient excuse, probably. The fact is that lot of projects are undocumented and most lines of code too. This brings us to a dangerous situation where only who has done the thing at the beginning will work on it because only he knows how things work. I think this situation for all mediumbig project is not tolerable. The project and also the code need to be well-documented, and all the knowledge must be written and shared across the team. This is fantasy? I know it may be hard to implement. I know we work under pressure, and the customer is always hurrying. But we have two options: do the right thing or suffer the consequences of the undocumented code.
In this article, I will reveal some tricks and Best Practices I experienced during my life as a developer. I can’t promise that time will stop, and you will have time to document the code before you leave the office. I can’t promise everybody will understand all your code. I’m not a lier, and I cannot do miracles 😄 . What I can do for sure is to share my experience and help you to write documentation more efficiently and let these practices coexist with business requests. I hope this helps.

Documenting IN the code, documenting while coding
The first goal of the Documentation routine is to remove any friction. The traditional approach requires complex context switch and makes the documentation uncomfortable. Think about the flow where you start creating the code and then (maybe days after) you complete it and start documenting. The mental strain on does that is high. You will need to remember all the things, find the right postman samples to add to the documentation, look at the code to find snippets… this requires a lot of time and effort.
What I propose is to document while coding. While you are doing something, you will write it. This means no context switch. This will save time and let you "flush" the thinking step by step. It also helps you while you are working because the documentation you are building will help you too.
Many IDE allow you to write documentation mixed with code and with some magic (or tools…) create the documentation automatically.
I don’t trust the automation where you will need to put the brain. I prefer to use regular code comment where I need it and separate documentation for explaining how the code works.
Documenting the code "inside the code itself" is helpful because it reduces friction between tools (you don’t need to switch between tools). In most of the cases, your files can be written in markdown and viewed in a human form, so it is a good solution.
Don’t postpone to tomorrow what you can do today
On my IDE, I always find a way to manage docs near to the code, and I document what I’m doing while I’m working on it. For example, if I prepare an API and I’m testing it with Postman, I will copy-paste the example on the markdown file as it is stable, commenting input and output. While I’m developing it, I will spend just one minute to do that. If I do days after that, I probably will spend a half-hour to double-check the API call, remember what I meant with such input and output… This practice will help you and your team to keep documentation updated.
The better comment is the one not written
While we are talking about the code itself, the first rule is that if you need to comment on a line of code, there is a problem. Theoretically, each line of code, each procedure name, each variable name should be selected to be self-explicative. In the real world, it is not always possible, or we have counterintuitive requirements. That why we are forced to comment part of code. Less you have to explain more clear will be for who read. Any time you are going to comment on a piece of code, you will ask yourself "Why." If it is because of harmful code, just change it.
PS: this doesn’t mean you do not have to comment on the code 😄 . I mean, the first option is to write good code that doesn’t need to be commented, the second one is to comment on it. Writing ununderstandable code and do not comment it is not an option.
One diagram worth more than a thousand words
There are may (thousand) of cases when things are too complex to explain in words. Even if you can, things hard to explain are often hard to understand. If you can, add a diagram to your explanations. This helps ever. This is useful for you because it helps to fix ideas and is pure gold for who will read the doc in the future (you may be one of them!).
We do not need a work of art. We need just a draw. So, spend less time possible on any esthetical issue and focus on the message you put into the diagram. The information matters, only this. I often use draw.io platform that is easy to use, free, and does not need anything more than a browser to work. It is a good solution but requires a small effort. You need to save the diagram to the cloud and download the image or save the diagram as a file into your codebase. In any case, you will need manual step and friction (open the file, draw, save, repone, fix…). Another solution that can be used is a sort of markdown for diagrams (Mermaid, PlantUML, but there are others), that can be integrated directly on the markdown file. Just an example below:
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
will produce a top-down flow like this:

To render the diagrams, you will need that your markdown rendering will support this syntax, or you can install some web browser extension.
What to take home
We can summarize the need for documenting the code in just one sentence:
Verba volant, scripta manent
This Latin sentence means that what you write remains, what is told… is volatile. We document the code for others, but also for us. Think to you, the "you of tomorrow," when you will work on that tricky feature. Or think to your self putting your hands in your colleague’s work. Do you prefer to start making reverse engineering to meet the functional requirements (if there is something written on the functional side) or simply read an explanation?
Documenting is not an option. More you use written communication and more traces you left. Starting write instead of telling is the first step to the continuous documenting. The next step is to find a process and some tool that helps to capitalize on each small contribution we give day-by-day.
To have good documentation, you will need the right tools, the right rules, but most important. You will need to create the right habits.
If done correctly, documenting code is an investment that will let you save more timemoney that what you will spend on it. If done just because we need to do it, it doesn’t bring results, and it is just a cost.