Introduce stornger type info and checks

[kirlat]

With some of the recent fixes, and doing changes to the code that I'm not familiar with, or the one I was familiar with a while ago,

It might be very useful to have some way to specify what values are expected for a method. With this, we would be able to understand what values are expected by the method and what cases should we handle within the method itself.

This could be extremely helpful for working with the code a parson is not fully familiar with, or the one he or she was familiar with a while ago. It also could benefit unit tests if we would know what values are allowed and what are not. Then we can build tests to cover all expected and non-expected values.

There is TypeScript and Flow, of course, but they are too heavyweight for our purpose, I think. We probably don't need to go full in with them. I think we might need something more lightweight and less intrusive.

Maybe something that, while in the debug mode, would check values during runtime and throw an error if an unexpected value is provided. This way will be able to catch cases when it is something out of expected range. In production this can be off, for better performance.

Or maybe we can agree on some extended JSDoc-type comments that will provide this information. If IDE supports it, it could generate helpful type hinting. Maybe we could also run some static type checks using that information.

Please share your thought and ideas on this. Thanks!

[balmas]

I think it would be great to have automated tests for method signatures although I would lean more towards a use of JSDoc comments-type approach than switching over to Flow or Typescript, which I think is not feasible right now. If there is a way to do this with a linter or similar that would be ideal.

[kirlat]

I think it would be great to have automated tests for method signatures although I would lean more towards a use of JSDoc comments-type approach than switching over to Flow or Typescript, which I think is not feasible right now. If there is a way to do this with a linter or similar that would be ideal.

Totally agree with this approach. I'm doing a research now on what's available in this field.

[kirlat]

I did some research and the best approach at the moment (other than using TypeScipt) is, on my opinion, to use JSDoc type descriptions along with the tools that use this data to provide type control and type hinting in the editor/IDE. This approach is well described in https://medium.com/javascript-scene/you-might-not-need-typescript-or-static-types-aa7cb670a77b.

There is support of this approach in at least three major editors/IDEs:

• Atom can support it via Tern: https://atom.io/packages/atom-ternjs
• VSCode: there is a built-in support for type checking. Here is an article that specifies how to use it there: https://medium.com/@trukrs/type-safe-javascript-with-jsdoc-7a2a63209b76
• IntelliJ IDEA family of products has a support for this since a long time ago: https://blog.jetbrains.com/webstorm/2012/10/validating-javascript-code-with-jsdoc-types-annotations/

@balmas, @irina060981, what do you think about an approach like this? If you find it useful, we can set up our own documentation standards and start following them. For example, I think that it might be useful to declare not only the type of the argument of the function or method but, if it accepts values from a certain list (as with constant values), specify those values too. I think that would be extremely useful when working with an unfamiliar code.

[balmas]

I agree with this plan. I particularly think that we should define, document and follow our documentation standards.

[irina060981]

I agree too, but we should remember that all these descriptions will increase developing time.
Also I don't understand how we would check descriptions, comments relevance on changes?
Sometimes I see outdated declarations in comments or even wrong copy-paste results.

[kirlat]

Also I don't understand how we would check descriptions, comments relevance on changes?
Sometimes I see outdated declarations in comments or even wrong copy-paste results.

That's the question of our discipline. Hopefully, if types are not up-to-date, warnings from a type checker will remind us to actualize the comments 🙂. Or we can use a TypeScript linter for checking comments (without using the TypeScript itself) and run it before the build, as the article suggests: https://dev.to/dakmor/type-safe-web-components-with-jsdoc-4icf

[kirlat]

I'm writing some documentation for the new changes and I've discovered that TypeScript has a tool that could do a static type-checking of pure JS, not TypeScript, files: https://github.com/Microsoft/TypeScript/wiki/Type-Checking-JavaScript-Files. It requires to use JSDoc comments in a "TypeScript flavor", which is the same or a superset of current JSDoc styles: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html. I think using TS-style docs would be good because it provides a consistent system of how to document things that we can stick to. I found that JSDoc itself is inconsistent or vague in some cases. TypeScript, on the other hand, is well developed, documented, and understood by many developers as many high-profile project are developed, or switching to, TypeScript.

If checkJs static type checking would work well, we can use it as a linter for our type system and run before every build as we do with other checks.

There is also a feature that we don't need right now, but might be handy on some occasions. It's a tool that can generate TypeScript definitions files (d.ts) out of plain JS with TS-style comments. It would allow our plain JS files to be integrated into a TypeScript project without any changes.

@balmas, @irina060981: what do you think? Would it worth trying to stick with TypeScript-style JSDoc comments for us? I see no harm in it, it even seems that JSDoc developers recognize the need to support the TypeScript syntax: jsdoc/jsdoc#1645

[kirlat]

There is also a TypeScript JSDoc plugin for ESLint

[balmas]

I have no objections.

[irina060981]

Me too :)

[kirlat]

Great! Then I will start using it to see how well will it work.