4 ms·
This is all true. It's also true of JSDoc (using the TypeScript engine or TernJS with standard JS) - but JSDoc also includes space for human readable descriptio
by ericelliott 7y ago
This is all true. It's also true of JSDoc (using the TypeScript engine or TernJS with standard JS) - but JSDoc also includes space for human readable descriptions which can be used to auto-generate thorough API documentation. And JSDoc has the advantage of working inline with standard JS.
It has the disadvantage of being annoyingly verbose compared to TypeScript though, so I guess the score here is:
JSDoc:
Documentation that stays in sync, powers editor tooling: 1
Works with standard JS: 1
Generates better API docs: 1
TS:
Documentation that stays in sync, powers editor tooling: 1
Requires compile-to-JS: 0
Less verbose than JSDoc: 1
WAY more fun to write: 1
Lacks prose descriptions for documentation: 0
JSDoc: 3
TypeScript: 3
- vikingcaffiene 7y agoI love JSDoc but it has the fatal flaw of being optional. It requires human discipline which, when your boss is breathing down your neck to get that feature out, you aren't gonna do. Same goes for robust tests etc. TS is self documenting even if it's less verbose you'll get more coverage overall in your system and maybe have some hope of being able to to back and write those JSDoc comments later. You also don't have to write as many tests as you can be somewhat assured of data integrity since you've defined a robust contract.
- ericelliott 7y agoTypeScript annotations are also optional. In my experience, TypeScript does not reduce the number of tests you need to write.
- vikingcaffiene 7y agoWell yes and no. Even if you don't add any type annotations you still get some implicit type safety. You have to opt out with an Any type of something to totally turn that off. Our experience is different with tests.
- ericelliott 7y agoThe TypeScript engine in VS Code does the same type inference for standard JS, and automatically downloads d.ts typings for libraries you use to enhance it.