[chimeracoder]

> As far as this discussion goes, I think that code is documentation.

"Code as documentation" can be an okay answer if the question is "what is the behavior of this system"? But it's a bad answer for the question "what is the intended behavior of this system, and what assumptions does it run under?"

Looking back at a piece of code months (or years) later and not knowing if a particular edge case that you're running into was actually the intended function or not is not particularly fun.

The power of writing documentation is not just in the end product; it's that it serves as a forcing function for the developers to confront their own thought processes and make them explicit. It's possible to write code that makes all of its assumptions explicit and clearly states its contracts up-front, but in practice, it almost never happens without significant external documentation (whether that comes in the form of explicit code docs, whitepapers, or ad-hoc email threads and Slack conversations that need to be pieced together after-the-fact).

[rhizome]

One of Fred Brooks's principles is that the manual is the spec, that there should not be any behavior in the software that is not in the documentation, and the documentation comes first.[1] A kind of old-school TDD.

1. https://en.wikipedia.org/wiki/The_Mythical_Man-Month#The_man...