Does: “Everything needs to be documented!” sound familiar to you? Do you like the idea?

This talk aims to make a case for the point that forcing developers to document every single piece of code will not result in good documentation. It will generate superfluous documentation and even impair the code quality!

It is really easy to write docs for bad code because short and indescribable named functions need to be explained while code that clearly communicates its intentions and actions does not.

The question discussed include points like:

What needs to be explained and what doesn’t?
Why is it a good idea to invest time into thinking about class and function names instead of documenting them?
What should be included in a commit message?
Can we get better and more meaningful documentation by writing less of it?
What is the gain of certain documentation concepts?
Further discussion where documentation is really needed and showing some common documentation “refactoring” patterns. By explaining ideas like “replace comment with function call” and “replace description with variable” the talk aims to save the time of every developer. Spending it once while writing the code and then saving the time of everyone involved by not making them re-read documentation that only tells them what they should already be expecting by reading the class and function names.

So stop wasting time on docs and start spending it on the one thing you know you care about: Code!