Counter-counterpoint: that documentation should not exist as comments in the code, but as separate, properly formatted documentation. Yes, there are tools (JavaDoc, Doxygen, etc) which will take specially formatted comments and turn them into standalone documentation. However, in my experience, using those tools did not encourage the sort of documentation you're talking about. The average JavaDoc is an auto-generated stub article that just lists the method name and the names and types of the arguments to the method, which is information my IDE already gives me.

Counter-counter-counterpoint: if you separate that documentation out, you'll guarantee it getting stale. Good documentation needs low friction - and preferably be part of code review process, so that the reviewer can spot when code changes without updating relevant documentation.

Documenting in comments is one way to achieve this, and it also brings two other benefits:

- High locality - you're likely to spot the documentation as you read the code it pertains to, because the comments are right there, mixed with the code.

- IDE support - interface-level comments are often automatically displayed in autocomplete and hover popups, so you can read them as you browse through suggestions and highlight interesting code fragments.

> Counter-counter-counterpoint: if you separate that documentation out, you'll guarantee it getting stale.

In my experience, having the documentation in the source code has very little effect on whether it gets stale. Unless you make checking for documentation changes an explicit step in the code review, documentation is going to get stale no matter where it is. And if you do have such a step in code review, then it's relatively immaterial whether the documentation is in a wiki or in formatted comments in the source.

> High locality - you're likely to spot the documentation as you read the code it pertains to, because the comments are right there, mixed with the code.

That actually brings to mind one of my complaints about relying on documentation that's inline with the source code. It's often too local. I can usually read a function and figure out what it's doing. Occasionally, when a function is doing something strange or counterintuitive, some documentation can be helpful, and I definitely acknowledge there's a role for comment-based documentation there.

More often, though, I don't want documentation to tell me what this or that function does, I want documentation to show me the big picture. What are all the components of this system? How do they communicate? How does user input propagate? Where does validation occur? These questions are almost never answered by comment-based documentation because of the locality principle that you cite.

In addition, the answers to these sorts of questions aren't likely to go out of date. After all, it's not like you're completely rearchitecting how validation works every week (and if you are, documentation is the least of your worries). These sorts of high-level questions are best answered on a wiki or some other tool that supports things like diagrams and well formatted prose text.

Yes, in an ideal world, we'd have both. Inline documentation which documents the design at a "micro" level and a wiki or some other knowledge-base which documents the design at a "macro" level. But we don't live in an ideal world. We live in a world where developers are pressed for time, and documentation is most often written after the fact. In this world, I would much rather have the wiki than the inline docs. I can, with a little bit of effort, figure out what each individual function is doing. It's the high-level "how it all fits together" design where I require assistance.

well I prefer some high level "unit-tests" (ofc they are not unit tests strictly speaking).

or perhaps I should name them "demo cases" or the like. Currently I am deeply sceptical about formats different from source code. "demo cases" require the dev to update them when they fail where as docs tend to get stale- (nearly) always.