Documentation is written in a human language, can include other media like graphics and is addressed to humans. We write documentation for the same reason that we don't produce maps at a 1:1 scale: documentation offers a higher-level description that can be grasped without having to understand all the code.

Not only is code not the best documentation, it's not documentation at all, outside of special cases where the entire code describes e.g. an algorithm and is encapsulated into one function.

Code should have a hierarchical structure, so one could read it on the high level of abstraction and also zoom in gradually, as necessary — this is what they usually mean by “code is the documentation”, plan the reading process as you plan the functionality.

It is a very important aspect of the readability, otherwise you will just sink in details when reading. But it is not easy to formally validate with tools, so naturally it is better to have both code and a picture and have discipline to keep them in sync.

> Code should have a hierarchical structure, so one could read it on the high level of abstraction and also zoom in gradually, as necessary

I agree with this. Some of the best code I've read and written was done in this style. Properly separating out components into a hierarchy of modules.

> this is what they usually mean by "code is the documentation"

I disagree with this. I don't think this is what people mean at all, because I don't think that most people do the first part. If they did, there wouldn't be so many problems with "code is the documentation". But most code is not written in a clear hierarchical fashion. Logic is weirdly commingled, and depending on the language you have an assortment of low-level bookkeeping mixed with high-level logic.

I think they literally just mean "code is the documentation". One of the best/worst programmers I ever worked with is a perfect example of this. He'd always insist on the "code is the documentation", and his code always worked. But his code was absolutely awful to read for anyone but him. By way of analogy, I don't have a file system for physical papers. I have a literal chronological (by access time) stack. No one but me can make use of it, but it's very effective for me because I have a really good memory (though not as good as it was 20 years ago, I don't actually do this anymore because I have to work with others). That's his code. No one else can go into it and actually understand it (at least not easily), but he can jump in and make exactly the necessary changes. The code is not the documentation until it's properly organized, and maybe not even then.

> I find this is nonsense. Code is the best documentation

Strangely, I find both gp and your claims to be nonsense. :-)

I've definitely experienced what you've experienced -- until you actually have code, you don't know what works and what doesn't work.

But it's frequently not at all obvious what code does, even in the normal case; and even code which looks obviously correct often has hidden complexities that you wouldn't have thought of.

I find trying to explain in a comment why the code I've written is correct is pretty good in wheedling out all the ways in which it's not actually correct.

So when things are really complicated, you need both: You need to have code that actually works, and you need to have text that attempts to prove that the code actually works.

> I find trying to explain in a comment why the code I've written is correct is pretty good in wheedling out all the ways in which it's not actually correct.

I found that well written, expressive tests accomplish that really well.

I use Spock[1] to write complex tests and I just can't recommend it enough if you're working with the JVM (Java, Kotlin, Groovy, Scala, Clojure).

We have several thousands of Spock tests and it's amazing how they have scaled with us... they've grown to support extremely complex workflows that have nearly zero accidental complexity and are easily readable even if you have no experience with it.

[1] http://spockframework.org

With Clojure, are you writing tests in the Spock DSL (or is that Groovy?) or are you writing the tests in Clojure and importing Spock as a library and extending its classes etc?

Spock tests must be written in Groovy, but they can call helpers from any JVM language, so we normally have lots of test helpers (traits) which we use to write tests with one-liners per action/assertion.

If you write your app in any JVM language, you can use Spock to t test it because Groovy really has excellent interop with Java, hence JVM languages in general.

"make sure it's something that can actually be checked" -- I'd love to find out about a sane (not purely academic, financially viable) way to do it. Since university days I know that a piece of paper is an irreplaceable tool - cheap and universal. I usually just draw it on paper, then code, then fix the code, then update the painting, and do it over again until both match each other and work. Never fails me.