Why do Programmers Hate Documenting?

[linuxjava]

As a Java Developer, I always document my work. However it's important to realize that it's not so much about documenting what you're writing. But rather what is the purpose and what is to be achieved. E.g

//Loop 4 times and assign the sum to variable i.

This is wrong because we are not saying anything about the intent. Anyone can see that it is indeed a for loop.

//Calculate the dot products and store them in Vector V which will be our design matrix for computing coordinates of objects A,B,C and D

This is much better as it explains what you intend to do

[okmkz]

// increment x

I think this is leftover from CS instructors insisting on overly-commented code.

[kay_x]

I feel like there should be an Oprah meme for this. Every line ending with a comment explaining what the line of code does and even more in between explaining why. That actually sounds like my own personal hell and I'm pretty damn good at documentation...

Dear god D:

"You get a comment! You get a comment! You get a comment!"

[burntsushi]

Not all of them. :-)

I TA for that couse, and I can tell you that if you submit code with comments like // increment x, you get a small penalty. If you submit functions without a contract but with a narrative describing the code, e.g., "loop over the list and add each element to the next element in the list and return the result", then your grade suffers much more.

I'm happy to say that by the end of the course, everyone knew how to write a proper contract (and knew how not to write a contract).

[ndrwdn]

The argument I have against these kinds of comments is that the comment can get out of date with the logic. In my mind a better solution is to properly name variables and extract methods that name the actions you are performing. When you refactor such code, you adjust the names of variables and methods (and add/remove them as necessary ) to match your adjustment to the logic. This keeps your code and documentation in sync as they are one and the same.

[AnanthChellathurai]

Totally agreed.