4 ms·

Hi, Author of the Article here :) I do not recommend JSDoc. Instead, typecasting has these advantages: 1. Precise self documenting 2. Much easier to maintain

Hi, Author of the Article here :) I do not recommend JSDoc. Instead, typecasting has these advantages: 1. Precise self documenting 2. Much easier to maintain and less verbose (see 1) 3. Requires no external tooling outside of the typecast functions which are hundreds of times less complex than JSDoc checking environments like Closure 4. Adds valuable run-time capabilities that JSDoc does not Sincerely, Mike

smt88 6y ago
> One approach involves using libraries or frameworks such as Flow or TypeScript that require transpiling or otherwise prepocessing the code. This is a crucial premise of your article, and it's untrue. TypeScript[1] and Flow[2] both support using their static typing without transpiling anything (i.e. the full power of the type systems in plain JS files). As far as type-cast functions, I've never found that I needed them after switching to TypeScript because the compiler checks that for me. If you use type guards on all un-typed input (JSON requests/responses, for example), then you don't need type casting at all because you always know your variable's type. That's the whole point of static typing. 1. https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html https://www.typescriptlang.org/docs/handbook/type-checking-j... 2. https://flow.org/en/docs/usage/ https://flow.org/en/docs/usage/
- millstone 6y ago
  It's JavaScript; you can't really know. Math.round = () => "haha"; Now `Math.round(3)` is a string.
  - SahAssar 6y ago
    No, when TS checks js it will check types for built-ins too: npm i typescript echo 'Math.round = () => "haha";' > test.js ./node_modules/.bin/tsc --allowJs --checkJs --noEmit test.js And you get: test.js:1:20 - error TS2322: Type 'string' is not assignable to type 'number'. 1 Math.round = () => "haha"; ~~~~~~ node_modules/typescript/lib/lib.es5.d.ts:708:5 708 round(x: number): number; ~~~~~~~~~~~~~~~~~~~~~~~~~ The expected type comes from the return type of this signature. Found 1 error.
- depmann 6y ago
  This premise is factually true for both TypeScript and Flow. Please explain how you could come to any other conclusion. I researched this 4 years ago, and since then Typescript has added the `--checkJs` option, but it still you to run a separate process to run the check, which seems to certainly fall under the category of "... otherwise preprocessing the code". And that's an edge case. If you've got TS installed, your almost certainly transpiling. Type guards are typecasting, just renamed to make you sound smarter. Flow requires a transpiler (https://flow.org/en/docs/install/ https://flow.org/en/docs/install/) and advocates the use of background process. Again, this solidly fits the above premise. These are enormously complex solution to a problem that can be resolved without transpiling by using 6 small functions and a sensible naming convention. Certainly there are many cases where that makes a lot of sense. I've developed lots of mission-critical JS that is very widely distributed and there are no type errors despite not using Flow or TS.
timw4mail 6y ago
Here are some reasons I like JSDoc: * The syntax is fairly widespread * Documentation pages can be generated from the comment blocks * You can use as little or as much as you like * Still readable without external tools * Uses block comment syntax I would generally advocate for a mix of JSDoc for public documentation, and type-checking/type-casting functions for actual runtime checks.

smt88 6y ago

> One approach involves using libraries or frameworks such as Flow or TypeScript that require transpiling or otherwise prepocessing the code. This is a crucial premise of your article, and it's untrue. TypeScript[1] and Flow[2] both support using their static typing without transpiling anything (i.e. the full power of the type systems in plain JS files). As far as type-cast functions, I've never found that I needed them after switching to TypeScript because the compiler checks that for me. If you use type guards on all un-typed input (JSON requests/responses, for example), then you don't need type casting at all because you always know your variable's type. That's the whole point of static typing. 1. https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html https://www.typescriptlang.org/docs/handbook/type-checking-j... 2. https://flow.org/en/docs/usage/ https://flow.org/en/docs/usage/

millstone 6y ago
It's JavaScript; you can't really know. Math.round = () => "haha"; Now `Math.round(3)` is a string.
- SahAssar 6y ago
  No, when TS checks js it will check types for built-ins too: npm i typescript echo 'Math.round = () => "haha";' > test.js ./node_modules/.bin/tsc --allowJs --checkJs --noEmit test.js And you get: test.js:1:20 - error TS2322: Type 'string' is not assignable to type 'number'. 1 Math.round = () => "haha"; ~~~~~~ node_modules/typescript/lib/lib.es5.d.ts:708:5 708 round(x: number): number; ~~~~~~~~~~~~~~~~~~~~~~~~~ The expected type comes from the return type of this signature. Found 1 error.
depmann 6y ago
This premise is factually true for both TypeScript and Flow. Please explain how you could come to any other conclusion. I researched this 4 years ago, and since then Typescript has added the `--checkJs` option, but it still you to run a separate process to run the check, which seems to certainly fall under the category of "... otherwise preprocessing the code". And that's an edge case. If you've got TS installed, your almost certainly transpiling. Type guards are typecasting, just renamed to make you sound smarter. Flow requires a transpiler (https://flow.org/en/docs/install/ https://flow.org/en/docs/install/) and advocates the use of background process. Again, this solidly fits the above premise. These are enormously complex solution to a problem that can be resolved without transpiling by using 6 small functions and a sensible naming convention. Certainly there are many cases where that makes a lot of sense. I've developed lots of mission-critical JS that is very widely distributed and there are no type errors despite not using Flow or TS.

timw4mail 6y ago

Here are some reasons I like JSDoc: * The syntax is fairly widespread * Documentation pages can be generated from the comment blocks * You can use as little or as much as you like * Still readable without external tools * Uses block comment syntax I would generally advocate for a mix of JSDoc for public documentation, and type-checking/type-casting functions for actual runtime checks.