[dkersten]

Code alone can never describe intent or rationale.

[ithkuil]

Indeed, you need both!

But documentation should not go too deep in the "how" otherwise it risks telling a lie after a while as the code changes but the documentation lags.