I used to own an API service at work, where we worked hard to ensure that the documentation was of a very high quality. When I got promoted and moved to a new team, I'd warned my manager NOT to hand it over to one team that was remarkably bad at their work. My manager did anyway.

During the transition, the new development lead said "I'm not going to read the documentation. If the code isn't self-documenting, we're going to rewrite it." Note that he said that not knowing anything about the service they were taking over. Also, it was in a language that had never established strong patterns for itself, so self-documenting when there are no strong patterns is generally meaningless.

Over the next 6 months, he proceeded to ruin the service to the point where it was impacting customers, and got fired for it. In any project of large enough size, self-documenting code falls apart unless you are remarkably good at it. IMO, Go's standard library is an exception to my experience.

> If users have to read a method’s code before they can use it, that’s not an abstraction! Good abstractions must be documented outside the actual code, or they do not abstract anything at all.

That’s not true at all. Good abstractions are methods or classes you can forget the details of and still use effectively. It doesn’t mean you shouldn’t understand them at some point.

It seems that JSDoc generated documents are an example of close to just this... you don't reference the code, you reference the docs. But the docs live inside the code for generation.

If you otherwise have separate documentation that is not generated, if the system/library has any complexity there's a greater chance that documentation doesn't align with implementation and bugs will creep in. That's not to mention stupid developer decisions, such as weird date normalization/structure or similar usage of magic numbers over text keys/flags.

It would be good to see some code samples with documentation for argument's sake, because the first thought is that you would be pretty much just duplicating pseudocode type of thing.

and code comments are eventually just lies...