Hacker News new | ask | show | jobs
by itsmeste 1348 days ago
This. Probably every TS codebase I ever worked in had zero to none function- or inline docs with people always claiming "documented by TS". I call that BS, and you can see that in their projects. "Typescript codebase" became the equivalent of "generic low quality codebase" imo.

I'll never understand why people need a programming language inside a programming language and refuse simplicity (i.e. using jsdocs, which has perfect IntelliSense support).
3 comments
auggierose 1348 days ago
I tried jsdoc + JavaScript for a while to minimise the distance between me and the browser, but in the end TypeScript was just the easier choice. Less documentation to type, and the checks are better. I found that using TypeScript basically like JavaScript + jsdoc delivers the best value. I avoid any advanced TypeScript features as TypeScript is just not a proper statically typed language.
link
CapsAdmin 1348 days ago
You can use some jsdoc in typescript, see https://www.typescriptlang.org/docs/handbook/jsdoc-supported...

However I tend to only use /** a comment */ before a type definition or argument which will add the comment along with the type in autocomplete.

I get the feeling you've stumbled more on the debate about commenting code/inline docs vs code that self documents. My general impression of Javascript developers is that they are comfortable adding comments whereas Typescript people are not so comfortable for some reason. Maybe because a lot of them are coming from Java and C# where writing clean code™ is more preferable to adding comments.

Personally I think there's a middle ground. I've met some Javascript developers insisting on adding a comment before each statement and I've met some java developers having a no comment policy in their codebase (so that pull requests wont merge if there are comments).

link
scrollaway 1348 days ago
This is entirely applicable to JavaScript codebases, except that at least in typescript you have less reverse engineering work to do.

If you want to have documented codebases, work with people who document their code. You’ll find that typescript doesn’t always mean undocumented, and incidentally you’ll find that documented doesn’t mean high quality.

Most high quality codebases in the JS ecosystem after 2016 ish are in typescript.

link