> Comments are not a solution for much of anything,
What are Unix man-pages but comments about the APIs they describe? Are you saying you would prefer to replace them with the TypeScript type-language?
As I see it TypeScript is a a solution to the problem of how to describe a function, what it does, what it expects from its arguments and what it returns. That information can often be clearly and simply expressed with a comment, rather than with a complicated type-declaration. And type-language only describes the syntactic behavior of a module, not its semantics.
When type-declarations become more complicated than the code they are describing I think we're at a point of diminishing returns.
The other purpose of type-declarations is to catch errors. But if a declaration is very complicated how can we be sure there's no errors in it?
> What are Unix man-pages but comments about the APIs they describe?
Documentation. Obviously not the same thing as inline comments in the code. You can generate documentation using comments (i.e. jsdoc), but comments are the weakest form of guidance for other developers. Types don't replace documentation, but are part of the same goal: making code easier to consume.
> When type-declarations become more complicated than the code they are describing
Do you find this happening to you often? JavaScript is a very permissive language, and most JS devs learn to write code in a way that is difficult to type. That's a part of the learning curve of the language. Part of using TS well, is realizing that complicated types are a smell for complicated behavior, and modeling your data in a conceptually simple way.
It's not just about labeling everything string or number, but making it impossible to use the code the wrong way.
> But if a declaration is very complicated how can we be sure there's no errors in it?
Simple. You test them. Same as any other code. How do you test your comments?
Sometimes, but as a last resort. I'd prefer types, tests and readable code over comments, and if I feel the need to leave a comments, I usually see that as a code smell
What are Unix man-pages but comments about the APIs they describe? Are you saying you would prefer to replace them with the TypeScript type-language?
As I see it TypeScript is a a solution to the problem of how to describe a function, what it does, what it expects from its arguments and what it returns. That information can often be clearly and simply expressed with a comment, rather than with a complicated type-declaration. And type-language only describes the syntactic behavior of a module, not its semantics.
When type-declarations become more complicated than the code they are describing I think we're at a point of diminishing returns.
The other purpose of type-declarations is to catch errors. But if a declaration is very complicated how can we be sure there's no errors in it?