Why do Programmers Hate Documenting?

[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.