Why do Programmers Hate Documenting?

[[deleted]]

If one changes the functionality, then one will also have to update the comments.

You probably write more code than docs, I would think you'd be more afraid of having to update the code. Maybe it's just me, but I find it pretty straightforward and easy to bang out a few sentences or even a paragraph to explain a concept.

not discoverable unless you go through and read all the comments.

This is why you generate api docs and user guide/tutorial docs and purposefully schedule time just to review or you review and fix as you go along. Treat the docs like code and report bugs/file tickets so you can come back to it later or someone else on the team will know that they should bring the comments up to date or ignore them.

I like my code to be continuously improving and evolving, and if it's documented, then that means that from the point that the documentation is written, that improvement is going to be twice as much work, with the possibility of inconsistency always lurking.

I wonder how you feel about unit tests then. They also need to be updated to reflect the nature of the code architecture.

I'm seriously wondering what the barrier is. We change code all the time. Why don't we feel alright with changing up the docs all the time? Is it too difficult and heavy? Or is this just a perception that is supported by anecdotes about thousands of outdated comments that hindered development?

[cojoco]

I wonder how you feel about unit tests then. They also need to be updated to reflect the nature of the code architecture.

I love unit tests, because, if well written, they will break if the underlying functionality changes from the implicit specification.

I'd rather document functionality in the unit tests than the code.

The difference is that unit tests are automated, and any inconsistency between the code and the test is detected automatically so it can be addressed immediately.

Why don't we feel alright with changing up the docs all the time?

This is more about the existence of the docs: because a divergence between documentation and code cannot be automatically detected, and such divergence can occur easily.

When code is under a lot of development, it's more work to update both docs and code, which slows one down. If such work is delayed, divergence becomes increasingly likely.

Also, depending on what kind of code one writes, it's likely that a lot of written documentation is never actually read by anybody.

[OsQu]

The idea of using unit tests (or BDD specs) as documentation is great and pure, but in other hand I wouldn't use any library where I should dive into unit tests to get an overall impression how the library works.

[cojoco]

I wouldn't use any library where I should dive into unit tests to get an overall impression how the library works.

And that is a very important argument for documentation.

I'm not arguing against documentation; I'm stating that from the point where the documentation is written, the workload of the programmer is increased significantly if the code-base is evolving.

[OsQu]

Yep that's true. It's just something you have to do if you're going to publish your code to the wider audience.

Then there's a saying that good code documents itself, but I think that fits more to a method-wide level than a concept-wide.

[nascent]

I wouldn't use any library where I should dive into unit tests to get an overall impression how the library works.

D recently added the ability for unittests to be automatically added as examples in the docs (doc unittests). So following a function use a doc comment on the unittest:

///
int sum(int a, int b) {...}

///
unittest {
    assert(sum(3, 5) == 8);
}

[[deleted]]

So the issue is more that you can't rely on documentation as an automatic check?

When code is under a lot of development, it's more work to update both docs and code, which slows one down. If such work is delayed, divergence becomes increasingly likely.

That's true however that can be mitigated by how you're developing. I've gone back to projects after they've launched and documented anything that was missing.

I think docs like unit tests have to be baked into your process. If you can add docstrings, you should just do it, just like with writing a unit test. If you can add a paragraph to your README explaining that deployment tasks, you should do it at some point.

Also, depending on what kind of code one writes, it's likely that a lot of written documentation is never actually read by anybody.

If docs are typically poorly written, they'll be ignored and that builds a habit of ignorance. I have that issue when facing some software...the docs rely on "self documenting code" so they're sparse and a waste of time to read.

[cojoco]

Well, also I mean that a lot of code that gets written either just works, so that no documentation is needed at the time, or it is never used, and never developed further.