[shadowgovt]

A dozen lines of nested types are like a dozen lines of source code, and I generally recommend treating them the same if they aren't legible: poke it with a REPL (in this case, try to declare a variable or new type that should work if your understanding of the types are correct) and see what the tools say.

(And, of course, as with other source code, illegibility implies more documentation needed. For type systems in particular, I think people tend to under-declare their types [i.e. they'll do "Record<KeyType, Array<{name: string, address: string}>" instead of "Record<KeyType, EmployeeRecords>"], which gives the compiler fewer hooks to shortcut talking about a complex type).

There is one thing consistently true about type systems that frustrates me: I write in procedural code all day, but basically all type systems are functional code. It is frustrating to have to spin my reasoning around to attack a problem in a different language structure when I've been doing straight-line statement-by-statement all day. I don't have a solution to that, but I observe the challenge.

[troupo]

> A dozen lines of nested types are like a dozen lines of source code, and I generally recommend treating them the same if they aren't legible: poke it with a REPL (in this case, try to declare a variable or new type that should work if your understanding of the types are correct) and see what the tools say.

None of these actions make types documentation. The necessity to do this makes them a hindrance at best.

> I think people tend to under-declare their types [i.e. they'll do "Record<KeyType, Array<{name: string, address: string}>" instead of "Record<KeyType, EmployeeRecords>"

Oh god, so true :)

[shadowgovt]

> None of these actions make types documentation.

By the same argument, code isn't documentation. And yet it is; all manner of style guides will tell us "Document the non-obvious, but let the code speak for itself when it's obvious." The challenge, of course, is obviousness is subjective. And I've definitely encountered type stacks where the author thought they were being perfectly clear and the reader didn't. But that makes it no different from other forms of docs.

I think the truth is types (and code) are a little of both documentation and implementation. After all, if code alone were sufficient, we'd just be hand-rolling 1 and 0 patterns to tickle the CPU directly; the existence of programming languages themselves are to bridge the gap between the minimum information a computer needs and human comprehension of what we're trying to get the computer to do.

(Whether types are docs at all, let me put it this way: every modern style guide I've found for languages where strong static typing isn't available declares I have to put the types in the documentation, especially for function calls and the like. That seems to heavily imply that types are a form of auto-checked documentation).

[troupo]

> By the same argument, code isn't documentation.

It isn't.

> all manner of style guides will tell us

A lie parroted ad infinitum doesn't make it truth.

[shadowgovt]

Can you clarify your belief that code isn't documentation? I'm far more familiar with the alternate philosophy that code is just another way humans communicate with each other (the computer doesn't care; the computer can take a machine-compatible binary from anywhere and execute it with no care as to whether humans understand the how or why of the program). Consider the "Literate programming" approach and tooling that operates in that paradigm (such as Jupyter notebooks).

Comments clearly aren't code, in the sense that they're a specific form in a language dedicated to being thrown out by the compiler / interpreter / etc (usually; I'm handwaving over the metaprogramming approaches like Doxygen that parse comments). But there's a reason we name variables `time_to_completion` instead of just `a`, or name functions (or have functions instead of jump pointers crammed into global variables), etc.

[amw-zero]

Documentation: "is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use."

That's a pretty [good definition I think](https://en.wikipedia.org/wiki/Documentation). I also think a type does provide explanation and instructions about how to use typed code. So, I think by definition, types are undeniably documentation.