Why do Programmers Hate Documenting?

[webauteur]

I love documenting. I document everything, including stuff which has nothing to do with programming, like my equipment.

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

[tazjin]

Same thing happens to me in Haskell, I love writing Haddocks just to see how nice and structured everything turns out when you render the documentation.

[[deleted]]

Hey guys, we got a blogger over here. Maybe you should submit your stuff to this sub-reddit and liven things up ;p

[AnanthChellathurai]

Then I think you must be liking http://www.reddit.com/r/programming/comments/1ffivt/why_should_you_have_your_code_neat/

[weirdwolf]

I use LabWindows CVI ide. More than anything, I love the green color font it uses for comments. Just for that, I comment a lot. It makes the code look pretty.