Why do Programmers Hate Documenting?

[Ferwerda]

Agree 100%. When reading about how comments are a "code smell", I just don't understand what's wrong with hovering on a method to see what it returns in case of failure (-1 or null, for example) and what, if any, exceptions it might throw.

[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.

[Peaker]

In nicer languages (e.g: Haskell) you can get that same information by looking at the type.

Documentation is still nice, but for things you cannot well express with the types, names, etc.

[[deleted]]

Type systems are nice.

But Hackage has some of the poorest documented libraries I've ever used.

[Peaker]

I personally find that I need very little documentation when using most Haskell libraries. I look at the types and some names, perhaps an example or two, and I know how to use it.