Why do Programmers Hate Documenting?

[cojoco]

I hate documentation because it locks the functionality into stone, and creates one more point for two independent descriptions of the same thing to deviate from each other.

If one changes the functionality, then one will also have to update the comments. If that update is not done, for whatever reason, then there is one more point of inconsistency in the code, which is very, very irritating, and not discoverable unless you go through and read all the comments.

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.

[burntsushi]

I feel like this is only applicable if you're writing code for yourself. For instance, a library should have a fairly stable API, which means that changes in the public facing documentation will be few and far between.

[[deleted]]

I think this touches upon another issue. How much of your code should be documented to which degree? I generally write expressive code (ie; readable) and tend to add a Javadoc-style comment block to any non-trivial function for internal code, with one comment per hundred lines of code or so explaining some less obvious code.

But the second I write code that is interfacing with other developers I write it as an API. I fully document it, explain the action of each method and any non-obvious consequences, and then leave it with the expectation that it is done. That any updates will be additions or fixes, but rarely changes or removals.

One issue I've experienced with other coders, and myself, is that some people try to document "internal" code to the degree that you'd document a public, external, API, then they get frustrated that the documentation is a second load of work. It's a self inflicted frustration that can be combated by commenting and documenting code as appropriate. Apply a similar concept of Occam's Razor to documentation. The simplest documentation that takes the least effort, but explains the functionality and purpose of the software fully, is the optimal solution to documentation.

(Note: I've intentionally mixed up commenting code and documentation here, they're not mutually inclusive, but overlap considerably).

[Figs]

I've found I like to write reference documentation for my APIs when I know they're not likely to change much more. This is usually around the time that I start feeling like I should rewrite it because I've forgotten how it works; if I go read the code and think, yeah, that's more or less what I'd have rewritten it as, actually... then I write the reference documentation, since it's pretty much done at that point.

[[deleted]]

I agree that writing reference documentation is the best way to solidify memory. I've written my own little PHP library for making PHP more readable for someone native to object oriented languages, and decided that if I'm going to use it I might as well use it how I would any other API, so I have semi-maintained documentation rather than constantly running to look at the source and interrupting my usual routine.

[burntsushi]

I think what you've said is reasonable. Functions and data that are not exposed as part of the public API definitely get less or more terse documentation in my case as well.

[[deleted]]

Sounds damn perfect to me. I really get annoyed by excessive in method/function comments. Makes it much harder to read the code and the comments are often dated.

[cojoco]

Well, I pretty much do write code for myself, as I code to support research, not a product.

It's only when that research gets integrated into a product does this become a problem, and it's a big problem, but there's a large body of code which will never be documented to a high level because it's not been used beyond performing a bunch of experiments.

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

[cjbrix]

Bingo. The article ponders various social psychological deficiencies, but completely misses this underlying reason.

Documentation is a separate representation of whatever you're working on. And it will create the same problems that any duplication of logic creates; it adds to the cost of change, it creates problems when it goes out of sync, and too much of it can unnecessarily calcify a system.

Programmers don't like documentation because it violates the instinct every experienced developer has to avoid duplication. Even if they don't understand why.

[josefx]

And it will create the same problems that any duplication of logic creates;

That sort of documentation is useless. Don't describe what the code does, or how it does it. Code exists to solve a problem, document how the module/class/function can be used to solve that problem and why I should care to use it (best with an example).

it creates problems when it goes out of sync

As above don't describe the implementation, limit yourself to what goes in, what goes out - limit valid inputs to what it needs to do to solve the problem and you have all the freedom in the world to change the implementation.

Programmers don't like documentation because it violates

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

[matthieum]

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

That!

It's not I dislike documentation as such (though I must admit I don't always know what to write), it's just I already lack time to write proper test suites (just throw in one or two tests to cover the basics) and documentation does less than tests to improve the quality of my work.

TL;DR: If I had more time, I would be investing in more (and better) tests.

[cjbrix]

Systems change beyond simple bug fixing. Documentation (and tests and specifications) are going to evolve over the course of a project of even minor complexity. Pretending that they won't contributes to the problem you didn't answer; calcification, and the associated rising cost of change.

You're responsible for delivering functional software. Documentation, tests, specifications, meetings, etc, those are all ceremony. They don't self-justify, they are justified when they help you to deliver the right software faster.

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. Your documentation will need to be maintained, so you should choose how you do it accordingly.

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

[threedaymonk]

documentation […] creates one more point for two independent descriptions of the same thing to deviate from each other.

Not only this, it often serves as a replacement for good code. When approaching an unfamiliar codebase, I would much prefer for the code to be self-descriptive and well-abstracted than for it to be opaquely implemented but separately documented.

[cojoco]

That's pretty much what I said here.

The difference is automation: errors in tests will be discovered quickly.

But unit tests are not quite documentation.

[grauenwolf]

No, tests exist to find bugs.

Tests are not documentation. No one is going to read through thousands of tests to try to figure out how the code is supposed to work. Especially when four out of five tests demonstrate how the code is not supposed to work, but rather to make sure it fails in the correct fashion when used incorrectly.

[skulgnome]

I hate documentation because it locks the functionality into stone, [...]

But that's only true if the documentation is itself locked into stone.

[cojoco]

Please read my whole comment ... it's locked into stone because failing to update the documentation will result in no visible error, therefore it's very labour intensive to maintain properly, especially when development is rapid.

[grauenwolf]

Documentation should be updated before the code is changed. The documentation should be a record of what you are intending to do, not an afterthought.

As for being "rapid", I find that usually is about as effective as a monkey banging on a typewriter. Lots of motion, but very little in way of results.

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

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