JSDoc and type-checking

[kungfooman]

Hey domink,

once you have separate files, it is easy to add type-checking.

Example JSDoc looks like:

/**
 * @param {number} len 
 * @param {number} overlap - Only used if respectWords === false
 * @param {boolean} [respectWords=true]
 * @returns {string[]}
 */
function splitOverlappingSubstrings(len, overlap, respectWords=true) {

You can enable type checking via jsconfig.json:

{
  "compilerOptions": {
    "checkJs": true,
    "strict": true
  }
}

(implying you are using VSCode or any other IDE that respects this)

[lizozom]

I thought of switching over to TypeScript instead. @do-me how does that sound?

[kungfooman]

If you want typing, add JSDoc, but don't kill my possibility to do <script type="module" src="..."></script> and require me to use a damn bundler because you feel enticed by TypeScript.

[do-me]

@lizozom I'd be a little hesitant towards TypeScript to have (the theoretical possibility of) a larger contributor base / a lower entrance barrier and a little less complexity. However, where do you see the main pros (and cons) for TypeScript in the context of this project?

[lizozom]

From my experience, it helps creating a cleaner code base and a good dependency structure as a project grows. I also don't think this is much of an entry barrier, once everything is setup. For example, see this version https://github.com/lizozom/SemanticFinder/blob/typescript/src/js/semantic.ts

However, I guess this ultimately depends on your intentions for this project. If you want to keep it small, I guess there's no need for TypeScript. I wrote what my intention was here. Let me know if this makes sense to you :-)

[kungfooman]

From my experience, it helps creating a cleaner code base and a good dependency structure as a project grows.

That's all hogwash bingo from the TS world, you literally have the same types using JSDoc while not making your JavaScript code unreadable while not requiring extra toolery you will step over every day.

I also don't think this is much of an entry barrier, once everything is setup.

This is so funny, it's like putting up a paywall on a newspaper and saying "it's not hard to read the newspaper, once you pay for it monthly"...

On another note, every experienced TypeScript user i know is using shorthand notations like string[] and not Array<string>.

I used TypeScript myself for years, but nowadays we write the year 2023, we have importmaps, JSDoc and ES6 modules, you neither need Babel, Google Closure Tools or TypeScript.

Of course you can still want to minify builds later using rollup/Babel and TypeScript would be just another layer introducing issues in the build script.

[lizozom]

On another note, every experienced TypeScript user i know is using shorthand notations like string[] and not Array.

I def use Array<string> 😋

Regardless, that's the tool that I like to use to organize my code. Does JSDoc have good vscode integration (autocompletion, return type hinting, etc)?

[kungfooman]

Does JSDoc have good vscode integration (autocompletion, return type hinting, etc)?

You need to realize that VSCode JSDoc is powered by TypeScript language server anyway.

[lizozom]

Tried it. Love it. I learned something new today @kungfooman 👍🏻