Static Typing as Documentation

I’ve started to learn Angular5. What’s interesting to me at the moment is its use of TypeScript, a superset of JavaScript that adds ES6 features, and optional static typing.

For years, especially in the web-programming world, dynamic typing was the rage (Perl, JavaScript, PHP, Python). Now types are back. Python has add-ons and JavaScript has TypeScript.

What’s changed? Well, for a while we all enjoyed “just getting things done”, without worrying much about compilers and having to declare types for every variable, function parameter, return value etc.

But then something funny happened. Web programming grew up. With the explosion of JavaScript on the front-end and back-end and enterprise-grade JavaScript frameworks we realized as developers we need to grow up too.

Besides the obvious advantages of compile-time error checking and improved tooling, static typing is a form of documentation. When working in a larger group we realized that we needed to add proper documentation to our JavaScript APIs anyway. I even started documenting my modules, methods etc. first. This allows me to think through the interface and puts me in the shoes of API consumers before I code.

It occurs to me that (optional) static typing bakes that documentation process into development from the beginning. It’s like testing first. Worst-case scenario is that we end up with a test suite and don’t have to spend time writing tests after coding the entire app. With static typed JavaScript, the worst case is that readers of your code can better understand what’s going on without having to understand how you implemented your code. And I bet it involves less tedious, manual documentation on the developer’s part.

I haven’t greatly investigated TypeScript yet. In fact I haven’t even used it in a real app so far. But I imagine that the auto-documenting tools would have a far easier job parsing the code than plain-old JavaScript. After all if it improves the tooling so much, then most of the work must be done already for a doc generator.

I’ll report back soon on my experience using TypeScript in practice. Until then I’ll investigate on…

Leave a Reply

Your email address will not be published. Required fields are marked *