[galaxyLogic]

A simple trick with plain JavaScript is to give all arguments default values. That gives a pretty good insight for anybody reading the code as to what "type" of arguments the function expects.

If you test-call such a function without arguments you will then know what kinds of values you can expect it to return.

The argument default values can not be inner functions but they can be any function that is in scope. Or if you are using classes it could a reference to any method of 'this'.

Then add some asserts inside the function to express how the result relates to the arguments. No complicated higher-order type-definitions needed to basically make it clear what you can expect from a function. Add a comment to make it even clearer.

[schwartzworld]

> That gives a pretty good insight for anybody reading the code as to what "type" of arguments the function expects. If you test

Only true if you're using very simple types, i.e. number and string. But "string" is pretty close to "any" and doesn't give you much info. If my function only expects two or three possible strings, it should be typed to only take those ones.

Comments are not a solution for much of anything, btw, and they only "work" if you read them. How many comments are in your node_modules folder?

[galaxyLogic]

> 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?

[schwartzworld]

> 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?

[galaxyLogic]

> You can generate documentation using comments (i.e. jsdoc),

So comments are a solution to something. Don't TypeScript programmers use them as well?

[schwartzworld]

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