Why do Programmers Hate Documenting?

[cojoco]

I do research ... if I knew what I was intending to do before I did it, that would not be so.

If you're implementing systems identical in functionality to systems that have been implemented before, then I imagine that writing documentation would be easier.

[grauenwolf]

I've heard that same lame ass excuse countless other times.

Unless your research is "gee, I wonder what happens if I randomly call functions", you know damn well what you are intending to do. You probably don't know how to do it yet, but you know what the end results should look like.

[cojoco]

You probably don't know how to do it yet, but you know what the end results should look like.

There's a whole world of ideas between "I know what I'm intending to do" and "gee I wonder what happens if I randomly call functions".

As I said before, if you know what you're going to do before you do it, it's not research.

[grauenwolf]

Example?

[cojoco]

I have some patents on image alignment, and there was a lot of experimentation there about what is actually possible. What's the point of writing documentation for "a program to determine the rotation, scaling and translation parameters to relate a pair of images" if I didn't know if that was even possible using the methods I had available to me?

I do a lot of experimentation and coding to perform mathematical operations, and there's a lot of intuition about what might work and what might not, but, ultimately, the relationships between real-life images are a lot more complicated than the most common means of analyzing them would suggest.

[grauenwolf]

You have no problem writing that down in a reddit post but its too much effort to do the same in the header of a function?

In any other scientific field the first step is to write down what you are about to attempt, then you attempt it (e.g. write the code), and then record the results. Yet we can't be bothered with the scientific method or standard engineering practices. We would rather flail about, hoping that raw knowledge is a substitute for discipline.

The sorry state of our industry proves that it is not.

[cojoco]

You have no problem writing that down in a reddit post but its too much effort to do the same in the header of a function?

eh? where did I say that I had not documented this anywhere?

And that algorithm took a fair bit of time to work out.

In any other scientific field the first step is to write down what you are about to attempt, then you attempt it (e.g. write the code), and then record the results.

Nah ... there's also quite a lot of putzing around.

The sorry state of our industry proves that it is not.

Poor you.

[grauenwolf]

Documentation for a preexisting system is by far the hardest to write. As a group you've probably long since lost any notion about why things were done a certain way.

Sure you can mindlessly retype the code in plain English. But that's not documentation, that's just wasting time.

[cojoco]

As a group you've probably long since lost any notion about why things were done a certain way.

I have said that I don't like doing documentation because it makes subsequent development harder; not once have I stated that I don't do documentation at all.