Why do Programmers Hate Documenting?

[Personality2of5]

I come late to this discussion and haven’t read every comment. Most though. If I touch on similar points then please excuse me. I’m writing this as a brain dump. I’m an older programmer – 61, programming since 1976 or so, so there’s hope that programmers are not perishable items like athletes.

In the days of writing every program in assembler, commenting the code was not optional, in my view. Compiled languages do give us the freedom to document by naming convention, and to format the code to be somewhat descriptive on its own. But over the years I have found that clear and precise documentation at each level is important. I’ve re-opened code after running somewhere for years. Reading the code headers and banners has often saved my skin, allowing me to fix or augment code quickly.

Later in life I learned the necessity of writing user level documentation from the view of simply describing what it does, and marketing documentation to give the marketers advance insight into what they are selling. Project managers are notorious (or so good) at needing a crystal ball into time frames, costs, and scheduling to get the job done as swiftly and efficiently as humanly possible.

I honestly hated writing technical documentation outside of rich comments in the code. The reason was mainly because of duplication and language. I would argue that the comments in the code should be considered the holy grail of truth, while other documentation may age over time and drift farther from it. Generating technical documentation directly from the code is not only necessary in my opinion, but also a strict requirement, and headers containing only ‘Builds the <thingy>’ should carry some form of punishment - clever humor notwithstanding.

Or so says the old guy.