3 ms·
+1. Another use of type systems that often falls under the radar is as documentation. Coming back or ramping up in a project that's typed is much more straightf
by aylmao 7y ago
+1. Another use of type systems that often falls under the radar is as documentation. Coming back or ramping up in a project that's typed is much more straightforward than one that isn't, for a few reasons:
- Types are documentation most editors will allow you to click through, which makes finding definitions much easier, as opposed to just comments.
- Types are documentation that's enforced by the type checker, meaning it's always there. Either the type checker can infer it, so the editor can display it even if the developer didn't write it, or it can't, so it asks the developer to write it.
- Due to the same enforcement as above, types are documentation that never grows stale.
Add to all this the fact good editors can parse and understand this documentation, and use this and provide code suggestions, etc. and it's IMO most often a very worth investment.
- ericelliott 7y agoThis 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.