is exactly the reason why you shouldn't be use static typing. We have a developer here who doesn't document any of their code and thinks that a good thing. Whereas in the dynamic typing world, they would be forced to use the good practice of documenting their code.
Code is never self-documenting, there are research studies on it.
But the types provides for let's say code-level self-documentation.
I can look at a function definition and see it returns an IReadOnlyStream. Well if I'm familiar with IReadOnlyStream I already know what I can do with that. If not I can quickly find the declaration, and based on that I can get a good overview of what I can do. If not I have something explicit to search the documentation for.
With languages such as JavaScript I learn nothing by looking at the function definition, and almost always have to dig deeper. If it's an unfamiliar code-base, then often much, much deeper.
You would be better off using dynamic typing and returning an Iterator.
The dynamic typing route of a small number of language defined types is far better than any developer declaring their own types whenever they want.
Why? Because it's simpler and simpler code is faster to write and easier to test.
The point is that most of the time I wouldn't know it's returning an Iterator, because it's poorly or not document. At least that is my experience.
Anyway, I was only speaking for myself. And my personal experience is exactly the opposite: I'm far less productive in dynamic languages when working on any non-trivial codebase, for the reasons I stated.
Seems like a comparison of Smalltalk using an IDE and Java using Notepad?
Not really credible is it.