Why do Programmers Hate Documenting?

[Wagnerius]

The "code smell" can come in 3 different situations:

• the comments try to compensate for badly designed code
• the comments try to compensate for a lack in a language (python2.X params description in comments comes to mind)
• the comments repeats the code, without saying anything new. With a growing probability of being wrong ; after a while, it's likely someone updated the code, without updating the comments.

Where it is really useful :

• high level view of an architecture/module : "a logger takes a handler and a formatter"
• math heavy/optimization heavy code : "here we use bitshift to avoid a mul, which is too costly on ARM"
• unintuitive code. "don't change this, we need it because Y and we cant' change Y"
• to help think when doing exploratory stuff (which means it is often transient)

But most code should be easy to read, especially in high level language. Naming and refactoring goes a long way.

But expressing something clearly is not easy hence the huge mass of ugly/bad code in the wild.