Introduction
Even in 2024, 12 years after the release of TypeScript and 17 years after the release of JSDoc, many people still don’t know why to use a static typing tool in their JavaScript project, even after it became a standard in the JavaScript/NodeJs community.
In this article, I’ll explain what TypeScript and JSDoc are, and why you should use one of them in your projects.
What they are
TypeScript and JSDoc are tools to allow JavaScript to have static typing. See below for an example of both of them.
TypeScript:
convert-string-to-int.ts (TYPESCRIPT file!)
JSDoc:
convert-string-to-int.js (JAVASCRIPT file!)
As you can see, TypeScript usually is less verbose than JSDoc, but on the other hand, JSDoc doesn’t require a build step, it works directly with comments in JavaScript code.
When to use them
You should use static typing in anything that meets at least one of the following requirements:
it will have more than 1 person working on it
The code has more than 1 file or more than 100 lines
The project has a chance to be improved (add new features) in the future
In summary, the only case where you shouldn’t use it is if you are writing a short script that only you will use and have no expectations of adding new features to it.
Pros
Before speaking about the pros, I must say that no matter how many articles you read or how good these articles are, there’s no way to describe how much better the developer experience is when you work with static typing.
No one can explain with words or arguments how good it is to work with a codebase that has static typing over an untyped one, not even the best of poets.
I, like many others, will try to translate this feeling into facts and data, but I ensure that it will not be enough to describe the exact feeling.
Avoid errors in production
This, without a doubt, is the biggest advantage of static typing. There are not enough words to describe how helpful it is, both in terms of avoiding reworks and saving money.
To ship things fast, mainly hotfixes, we end up not having the time to write unit tests or test all the possible flows of a solution. If you work with pure JavaScript, there’s no way to ensure that:
All the variables that you are using exist
All the variables that you are using are declared
You are using allowed methods for that type (ex: you can use map in a number variable)
If you are comparing equivalent variables (you shouldn’t compare an number with an array)
If you do not test your code extremely well, you will have to work on it again to fix a bug, spending precious time on something that you could have coughed before. Bugs caused by these things may sound stupid, but they are the ones that happen the most.
Using static typing, you ensure safer and faster development, decrease absurdly the amount of bugs in production, and allow the developer to focus only on the thing that really delivers value: The business logic.
No unnecessary testing
Most legacy projects and cloud-intensive projects (projects that you many resources exclusive to the cloud) have a difficult process of running the code locally, or even worse, you have to deploy it to be able to execute without mocks.
The process of running things locally can be very time-consuming and exhausting to the developers, and being able to avoid it saves a lot of resources (time, money, patience, cloud resources, etc).
With static typing, the code is very predictable, and you can develop everything knowing what is happening in each part of the code, and track the execution very easily, this makes it so that the only time you need to run the code is after finishing development, to truly test if everything works as expected.
No outdated docs
Most of the time (if not all of them) when we try to write documentation about a function and try to add examples of input/output it becomes outdated in the blink of an eye. Developers never remember to update the docs, and Scrum Masters never want to allocate enough time to do it.
With static typing, the code is a live doc. It’ll never become outdated, because when developers update the code, they will be updating the docs.
Avoid problems with CommonJs / ES modules
After the implementation of ES modules in NodeJs, many libraries started to migrate to this new way of writing code, so their new versions (more secure, reliable, performative, and with more features) aren’t compatible with older versions of JavaScript, which leaves you stuck with unsafe outdated versions.
Guess what is compatible with both CommonJs and ES modules without having to change anything in your code (only a few lines in the configuration)? Exactly, TypeScript (unfortunately, I think that JSDoc doesn’t have this advantage).
Autocomplete & avoid miswriting
Instead of having to remember every property and method that something has, let static typing and your favorite IDE do it for you!
This decreases development time because:
You do not have to go back and forward to consult the properties of something
You can type only the first letters of the property/method and press enter (or select the right suggestion, then press enter), and it will be autocompleted
It also avoids the miswriting of words, a thing that causes more bugs in production than it should.
Less loss of knowledge & no time wasted
It’s common that in a project, different developers write specific parts of the code, and what may seem very obvious to the person writing it, may not be intuitive to everyone.
If other developers work on a new thing written by another person, they will have to spend some time understanding it before being able to make any changes. Using static typing allows developers to cut A LOT of time understanding the values of the variables and the flow of execution.
If the developer who wrote that code leaves the company/team, it will not have an impact as big as it would have, because all this documentation is directly on the code. Easy to find and easy to understand.
Developers also need to rely less on pair programming to be able to work on a project, if it’s well-typed and simple enough, they may be able to make improvements/changes without even talking to someone in the project, increasing absurdly their efficiency.
Modern and attractive to developers
TypeScript is one of the most loved languages based on the Stack Overflow Developer Survey, here’s the results of 4 consecutive years:
2020:
2021:
2022:
2023:
JSDoc is not present in the survey, so I do not have any kind of data to say that it’s a good option. The only thing that I can say is that HTMX is using it, but it’s a very simple library.
On the other hand, we can say that from this survey, developers have preferred TypeScript over JavaScript for most of the recent years.
Flexible
You do not need to type everything. TypeScript and JSDoc can guess the type of most of the things, which makes it a lot easier and less verbose than other languages like Java or C.
For TypeScript, in the worst-case scenario, just use any. any is “the joker” type, it represents anything, and because of this you should avoid it at all costs, but if you are short on time or don’t want to be blocked by the lack of a type, you have this option.
For JSDoc, simply do not comment on anything, it’s pure JavaScript!
No more unnecessary refactor
I’ll explain more about the why of it in the It has a high learning curve section, but I’ll give some spoilers here.
Codebases with ununderstandable code need to be refactored, and codebases that don’t have proper documentation (that we agree is impossible to maintain if it’s separate from the code) have a higher amount of sections impossible to understand without a lot of digging and time to analyze.
Refactors should not happen because your code is impossible to understand, but because of performance issues or changes in the business logic. having to do the same thing twice is bad for everyone: the developers, the users, and the investors.
More independence for developers
It’s common for long-lived projects to have multiple people working on them, and it always takes some time (both for the newcomer and the more experienced developers) to make newcomers proficient with that codebase.
With static types, we can decrease the necessary time A LOT, because developers can understand at least the basics of the code alone, and need the help of other developers only to understand more complex business logic (if they aren’t documented in the code, but this is a topic for another article).
It makes it easier to have newcomers in the projects, decreases their learning curve a lot, and allows them to work on the project with less risk of breaking something, increasing the efficiency of your team as a whole.
Cons
More complex build step
The only con that TypeScirpt has is that its build step is more complex (because let’s be real, nowadays ALL JavaScript projects have a build step already, so it only makes it a little more complex).
You may need proper plugins or adapters to integrate your build process with TypeScript, but nowadays we have a bunch of mature and ready-for-production libraries, plugins, tools, and whatever you need to make it work.
I’m not gonna lie, it may cause you some trouble the first time, like most other tools in the JavaScript ecosystem, but not enough to overtake the pros.
If you choose to use JSDoc instead of TypeScript, this only con that TypeScript has is gone, but a new one appears: JSDoc doesn’t work very well with more complex types if you don’t use classes to represent them.
Debunking arguments
It’s verbose
To compare 2 things, you have to make them equivalent. For JavaScript code to produce results similar to TypeScript, you must have documentation with it, or else you would be comparing an unfinished sketch with a complete painting.
Documenting directly in the code, in ways more familiar to developers than having to dissertate about the things and add (soon-to-be outdated) examples to them, is not only less verbose but also less stressful to the developer, that I’ll not leave their familiar place.
It has a high learning curve
Static typing requires you to write a few more things, but the learning curve is not related to the extra : string that you have to write, but how difficult it is to work with that codebase.
Without static typing, you need A LOT more context to understand what is happening in the code, what values a variable has, and what business logic is being applied.
Let’s see an example:
function processOrders(orders) {
}
With only this information, can you determine what values does orders has? You may say “It’s an array!”, but guess what? You are wrong. orders is an object. Which properties does it have? Good luck spending at least a minute looking at the code to figure it out.
Are the properties optional? Do they always exist? They are objects, arrays, or strings? Does another member of your team have this knowledge or the person who wrote this code is long gone?
Static typing by itself reduces the learning curve by a colossal amount.
With pure JavaScript, each person who would work at something related to processorders would have to go through the same process:
Asking themselves what orders is
Spending a lot of time inside the processOrders logic trying to figure it out
If it requires a specific behavior of processOrders, probably asking other team members for more details and spending their time also
Let’s put it in numbers, to make it more fun:
A team of 5 people, each one making $ 100k/year
Let’s say they must work with processOrders one time every 6 months, time enough to forget about specific details
They spend 5 minutes to figure out EVERYTHING they need (Yes, I’m being very, very optimistic here)
A project usually has thousands or at least hundreds of functions, all of them similar to processOrders, but let’s consider only a small project here, with only 10 functions.
5 developers * 10 minutes / year * 10 functions = 500 minutes per year
If each developer makes 88 cents per minute, It would cost $440 only to figure out what 10 functions receive and return. This is unproductive time, that doesn’t generate any value, in the BEST case of a fictional scenario where your magical project only has 10 functions, and not the real-world where a project has thousands of these.
Now, with TypeScript:
interface Orders {
ids: Array<number>
skipTypes?: Array<string>
}
interface ProcessedOrders {
total: number
success: number
skipped: number
}
function processOrders(orders: Orders): Promise<ProcessedOrders> {
}
I know that this is a terrible unintuitive function, but this happens in the code. It shouldn’t, but it does, so it’s better to at least have it documented.
Contrary to the pure JavaScript version, here you have all the context that you need to understand everything that the function receives and returns, whether it’s optional or not, and the basic principle of what the function does.
After all this, you can still argue many things, like “It’s a Clean Code problem, not JavaScript’s problem!” or “It’s a Lack of Documentation problem, not JavaScript’s problem!”, but I ensure you, all of these things are DIFFERENT problems that yes, happen in the code, that I may address in other articles, but aren’t the focus of this one.
Some libraries don’t support TypeScript
This is the magic of TypeScript: You do not need your libraries to support TypeScript.
You can use the library without any typing, and it will work the same, but since it will be harder to work with a pure JavaScript library (because it doesn’t have any of the advantages mentioned in this article) you probably should consider using a different one.
I’ll have to learn something new
Yes. We as developers have to learn something new every day. it’s part of our jobs. We are here to create technical solutions for problems, to be a reference, and to figure out how to solve the problems that we face.
Learning something new that has so many benefits is an effort that makes the time worthwhile.
Conclusion
After knowing how much static typing tools help development, without any considerable cons against it, there’s no way to deny how beneficial it is for everyone: The developer, the users, and the finances of the company.
I hope that this article helps you to understand it and convince your pairs to improve your development experiences.
