Introduction
Even in 2024, 12 years after the release of TypeScript and 17 years after the release of JSDoc, many people still dont 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, Ill 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.
As you can see, TypeScript usually is less verbose than JSDoc, but on the other hand, JSDoc doesnt require a build step, it works directly with comments in JavaScript code.
TypeScript
convert-string-to-int.ts (TYPESCRIPT file!)
JSDoc
convert-string-to-int.js (JAVASCRIPT file!)
Pros
Before speaking about the pros, I must say that no matter how many articles you read or how good these articles are, theres 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, theres 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
mapin anumbervariable)If you are comparing equivalent variables (you shouldnt compare an
numberwith anarray)
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. Itll 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) arent 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 doesnt 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
Its 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 its 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, heres 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 its a good option. The only thing that I can say is that HTMX is using it, but its 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 dont want to be blocked by the lack of a type, you have this option.
For JSDoc, simply do not comment on anything, its pure JavaScript!
No more unnecessary refactor
Ill explain more about the why of it in the It has a high learning curve section, but Ill give some spoilers here.
Codebases with ununderstandable code need to be refactored, and codebases that dont have proper documentation (that we agree is impossible to maintain if its 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
Its 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 arent 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 lets 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.
Im 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 doesnt work very well with more complex types if you dont use classes to represent them.
Debunking arguments
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 to 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.
Lets see an example:
function processOrders(orders) {
// Logic here
}
With only this information, can you determine what values does orders has? You may say Its 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
ordersisSpending a lot of time inside the
processOrderslogic trying to figure it outIf it requires a specific behavior of
processOrders, probably asking other team members for more details and spending their time also
Lets put it in numbers, to make it more fun:
A team of 5 people, each one making $ 100k/year
Lets say they must work with
processOrdersone time every 6 months, time enough to forget about specific detailsThey spend 5 minutes to figure out EVERYTHING they need (Yes, Im being very, very optimistic here)
A project usually has thousands or at least hundreds of functions, all of them similar to
processOrders, but lets 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 doesnt 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> // Skip orders if they have specific types
}
interface ProcessedOrders {
total: number
success: number // Amount of orders that were succesfully
processed skipped: number // Amount of skipped orders based on input filters
}
function processOrders(orders: Orders): Promise<ProcessedOrders> {
// Logic here
}
I know that this is a terrible unintuitive function, but this happens in the code. It shouldnt , but it does, so its 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 its optional or not, and the basic principle of what the function does.
After all this, you can still argue many things, like Its a Clean Code problem, not JavaScripts problem! or Its a Lack of Documentation problem, not JavaScripts 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 arent the focus of this one.
Some libraries dont 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 doesnt have any of the advantages mentioned in this article) you probably should consider using a different one.
Ill have to learn something new
Yes. We as developers have to learn something new every day. its 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, theres 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.
Top comments (0)