Things I Learnt The Hard Way - Documentation Is a Love Letter To Your Future Self

We all know writing the damn docs for functions and classes and modules is a pain in the backside. But realizing what you were thinking when you wrote the function will save your butt in the future.

When I say that it will save your butt, I don't mean the documentation will tell you something like "Here are the lotto numbers in 2027"¹ or "If John complains about your future code review, here is some shit he did in the past".

I mean, it will explain how the flow of your code is expected to do. Imaging this: pick your code and replace every function call to its documentation. Can you understand what it is expected by reading that? If you can, congratulations, you won't have a problem in the future; if you can't... well, I have some bad news for you...

One point that may come here is "Code is its own documentation" or "self-documenting code". I do understand, and yes, simpler functions may make the documentation redundant (for example, if you notice that you need a function that multiplies two numbers -- and only do that -- giving it a description of "Multiples two numbers" may look redundant), but you have to ask yourself why you needed such simple function. Why it exists? Where it sits in the general data flow?

Another thing you can document: rarely used functions. One example is Java Collectors: In Java, you can create a stream of data, which you can apply transformations and such and, in the end, you may put the resulting collection of data into another structure -- a list, for example. The thing is, collecting to a list is pretty common, but collecting into a map, with a function as key and another value as value, splitting the result into two different data blocks, is not that common. Because it is uncommon to see such collector, it is a good idea to add tips on what each option is.

That's the things you need to document.