Sorry if this is what you were specifying when saying "executable documentation", but have you seen the way Rust handles documentation tests [1]? The idea is to provide documentation via comments before a function definition, and inside this documentation you can provide example uses. The test-runner automatically extracts these examples and verifies them. In this way, your documentation and tests are always in agreement with each other, and a developer can be aware of expected behavior by reading either the code comments or the auto-generated html docs.

I'm rather fond of this system, personally.

1: https://doc.rust-lang.org/book/testing.html#documentation-te...

Thanks, you got me testing rustlang testing facilities. Very enjoyable. Makes you want to do low level programming 10x more than with c/cpp.

That's assuming the code even makes sense. Have you ever been looking at some code, having no precise idea what it does, with no commit history to give an explanation? That's when unit tests would be useful documentation.

If I start working on a new project and they have tests, I always start there. Heck, if I resume working on an old project of mine, I start with the tests.