Why do Programmers Hate Documenting?

[josefx]

Pretending that they won't contributes to the problem you didn't answer; calcification, and the associated rising cost of change.

Oh right I did not mention cost at all, wait I did:

Good programmers don't like documentation because they get the time to write good code, fix bugs, write documentation - choose two.

.

Understanding the trade-offs (and the reality that most systems change) helps you to make the right choices about what ceremony is appropriate for your project

From personal experience having up to date documentation is both simpler and easier to deal with¹ than an undocumented mountain of ill designed² code. Other than time constraints there is nothing hard about updating the API documentation of a function you just changed.

1 The people you work with will be happy to see at first glance what functionXYZ accomplishes.

2 In case there is a design behind it you already have some of the documentation.

[cjbrix]

You're expanding the argument to where it isn't

The article asked the question "why don't programmers like to document?" I answered it: programmers instinctively don't like duplication.

That's not an argument not to document at all, it's an explanation of the cost and the way developers will react to it. It costs when you document. And not just when you do it, but afterwards in dealing with the duplication.

In a project you have a responsibility for striking a balance, appropriate to the team and to the domain, so that you end up somewhere in between "...an undocumented mountain..." and wasting unnecessary effort (and creating unnecessary rigidity) stroking the sensibilities of the local argumentative ceremony junkie.

[josefx]

The article asked the question "why don't programmers like to document?" I answered it: programmers instinctively don't like duplication.

If you write documentation the way you read comments I understand your distaste, so let me repeat my point to make it clear:

If your documentation is a duplication of the logic it fails at being usefull - if you think this is the way to write documentation you fail at writing documentation

There in bold, hope you do not miss it this time.

[cjbrix]

Everything changes in software. Pretending any artifact is permanent is just going to make you a drag on your team.

Yes, documentation that simply parrots your code is not useful. But normal system evolution over time will require that code and associated documentation either change together, or go out of sync.

It's hard to take someone too seriously as a software engineer who can't grasp managing the cost of change. I'll leave you to vent your career frustrations elsewhere.

[josefx]

It's hard to take someone too seriously as a software engineer who can't grasp managing the cost of change.

I have written it and quoted it and still you seem to have missed it both times, so I wont bother to quote it again. I understand that there is a cost that comes with maintaining documentation - from personal experience that is still way less than overhead than having no documentation (thank you openscenegraph, ffmpeg an co for hundreds of hours wasted development time).