This is one of the great discussions among developers: document or not document your code? Is it worth writing documentation in your code?

I thought this topic was completely overcome and it was clear that, except some few occasions (implementing a public API), documentation was not necessary. Until I saw a code review where the reviewer pointed out the lack of documentation as an issue. Really?

I was one of those who used to document my code... or at least I tried. I was so convinced that code had to be documented. As a backup or reminder for my future myself or any other developer luck enough to end up in my code. Although I always realised it was always out of date. And by then, I already wondered: what is the purpose of documenting the code if the documentation is always outdated?

Until several years ago I read the book Clean Code.

I saw it "crystal clear", there is no need to document your code if you code your documentation.

With this I mean to use meaningful variable and method names. If the name of the member already tells you the information that is keeping and the name of the method tells you what the method is doing you can end up reading the code without the need to figure out or document what your code is doing.

Extract as much code as you can to methods. Even if you end up having a method with only 3 or 4 lines. Each method should do one thing and only one thing. And the name must explain what it does.

Each member of a class must have a name that only reading it you know which information you can find there. Same for variables and input parameters.

Following this simple steps you can have a code you can read, having the documentation right in the same code.

Yes, I know, there are those times you have to implement code with a complex algorithm or you are copying a code you found on Internet which might be complex, you might not understand and you might not extract in simple and meaningful methods. Yes, there are always exception.

What do you think? Do you document or write the documentation in your code?

This post was originally published in Medium