Hacker News Reader

Code alone can never describe intent or rationale.

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.