I'm a selftaught (web) developer. On sunny days, you can find me hiking through the Teutoburg Forest, on rainy days coding or with a good fiction novel in hand.
First off, you've obviously dedicated a lot of time and research into this article. I found several very valid and well-thought points, some which I do not agree with and a few that I find simply incorrect (= could not cross-verify anywhere).
TL:DR - I have added a few counter arguments for each of the points of this post, all of which are very subjective. I love JSDoc, especially in environments that do not support TS. Some of your points, in my eyes, might be a bit misleading to devs getting started with the language. You're invited to disagree with each of them, hence the tone.
1. The Learning Curve.
As you state, using TS or not heavily depends on the use case. Given you're working on an enterprise-grade project with several developers, comparing the cost of learning against the cost of later maintenance, I find this no valid argument against Typescript.
Quite the opposite - since it's hard to learn, it's a valuable asset for your portfolio. Learning TS increases your net worth and distinguishes you from other developers.
2. Strict Type Checking System.
The example you provide is literally a type-only bubble sort in TS. I do not find it to be a practical example of static type checks. Applying this principle to anything but snippets feels like writing the whole codebase in a @types directory.
I agree with your statement that complex types are, well, complex. That's why they're being used. Compared to languages like Rust or Java, you do not have to type your whole project. If types are too complex, you're free to leave them out.
3. Verbosity And Lack of Readability.
True, large TS codebases are a mess. Just from my experience, it's not the types per se that cause havoc, but the way they're named and maintained. If you and your co-devs handle them properly and prevent them from rotting, this problem can largely be circumvented.
Regarding one of your alternative solutions: In my eyes, JSDoc is more verbose compared to TS. You can see it in your own example - in many cases properly named variables can easily replace JSDoc comments.
4. Lack Of Intuitive Syntax
See point 1.
5. Lack of Compatibility.
The example you describe is not a problem with the language. Why should I ditch the language if the environment does not support it? That feels like saying 'I ditch Python because it does not run in my browser console' in 2015. This problem led to a great innovation called Pyscript.
6. Low Productivity.
Typescript can be slow and cumbersome, especially compared to more streamlined languages like JavaScript or Python.
Frankly, sometimes I have the feeling I only write types for the compiler's sake. But writing types, enums and interfaces forces me to think through by data structures and optimise on the go. And I would always choose taking weeks longer for the initial release than spending months patching up my mess.
When you are trying to rapidly prototype something during a Hackathon, the last thing you want is to deal with the extra overhead of Typescript.
I do want it because I'll spend only the weekend writing on the code. And I'll have forgotten most of the data structures in the time between. Because I am lazy and do not document a lot (sometimes ChatGPT does that for me), I'm happy seeing my previous thoughts neatly formatted as interfaces waiting for me to come back.
All of my previous Hackathon submissions, after learning the language, are written at least partially in TS. One even won me a grand prize. And I'm happy for the static types, because now I can keep developing on it without reviewing the whole codebase.
Using Javascript is great because of the short time-to-market, but in my eyes, it's largely outweighed by maintenance costs for enterprise grade apps.
7. False Promises.
Also, I'm not too fond of TypeScript because it's a language that tries to sell you the idea of solving all JavaScript problems
If this is true, I have a misconception of the language. Is this your personal opinion or has this been stated by one of the core development team? If so, can you please provide a source for this statement?
For me TS is pretty much this:
The goal of TypeScript is to be a static typechecker for JavaScript programs - in other words, a tool that runs before your code runs (static) and ensures that the types of the program are correct (typechecked).
If you're serious about becoming a great developer, you should not settle for a language that limits your creativity and hides the true power of the language.
I don't think TS limits my creativity. All types are optional, nothing prevents me from typing everything with any. But I find it more elegant and more responsible towards my customers to write robust code. With great power comes great responsibility, after all.
9. Giant Corporation Abuse.
Yes and no.
If you don't know yet, Microsoft has a long history of being an anti-open source and anti-Linux.
Fortunately, Microsoft is not solely run by Steve Ballmer. Of course they used to doom Open Source, until they figured how to capitalise on it. And now, there's software like this:
This happens in Javascript too & does not really count as a reason to ditch the language
11. Not A JS Superset.
I am unsure how to respond to this statement and the example you provide properly. In general, you're not wrong. Since TS uses static types, types must be known at compile time. This also goes for your example. Yet as stated in point 8, I see no problem in this, but an opportunity to make my code more robust:
typeFoo={bar?:number}constfoo:Foo={}foo.bar=42
12. Slower Compile Time + 13. Additional Transpilation Step
True, that's the price you pay.
14. Lack of Performance.
Usually, you do not ship TS code to production.
Performance can indeed become a problem during development when using TS in Node.js using ts-node or nodemon. In the frontend, Vite does a good job at solving performance issues.
15. Writing Unit Tests.
I find it even easier because all my types are already declared and, if I did a good job, count for tests and the software.
For example, if I need to change a single property of an object used in a test, I would have to go back and modify the type definition and the test code itself.
And where's the problem? I would want my co-dev to document a change like this somewhere.
I still remember an upgrade from formidable v2 -> v3, where a single property name changed and I spent a whole week figuring this out (in a JS codebase) because the app would keep crashing. Okay, I haven't read the breaking changes in the log, but I was still quite upset about such a minor change making such a huge impact.
16. Types Are Not That Useful.
See points 1-15
17. Heavier Tech Debt.
Typescript can be a major issue when a project's scope, tech stack, or architecture changes halfway through the process
Sure there are madman PMs changing the architecture halfway through the project. But that's not technical debt, it's poor planning.
Also:
You now have to go back and refactor all of your existing code from Typescript into the new technology stack, which can take considerably longer than if you had chosen the correct language from the beginning.
Boy am I glad the concept of static typing is language agnostic.
Nice to meet you, ma fren 🫡. Sorry, I ain't DEVing that much ✍️ , primarily due to the nature of maintaining Open Source projects 👷, while also gigging 💰. Anyways, stay humble like a bumblebee 🐝.
First off, you've obviously dedicated a lot of time and research into this article. I found several very valid and well-thought points, some which I do not agree with and a few that I find simply incorrect (= could not cross-verify anywhere).
Thank you so much for your kind words! Oh thanks! I'm glad you appreciated all the work that went into this article. It's true that a lot of research and time went into it, and I'm pleased to hear that it was worth it. I'm glad that it resonated with you. Thank you for taking the time to read it.
I love JSDoc, especially in environments that do not support TS.
This!
You're invited to disagree with each of them, hence the tone.
Let's do this!
1. The Learning Curve.
Quite the opposite - since it's hard to learn, it's a valuable asset for your portfolio. Learning TS increases your net worth and distinguishes you from other developers.
Of course, I mean if you want to pay me xxx$ , I can learn whatever the heck you wanted. That's not the point. As stated in the article, the main point is:
In short, the learning curve associated with Typescript can be quite steep and require significant time and effort to master.
2. Strict Type Checking System.
Applying this principle to anything but snippets feels like writing the whole codebase in a @types directory.
Agree with this.
3. Verbosity And Lack of Readability.
True, large TS codebases are a mess.
This!
If you and your co-devs handle them properly and prevent them from rotting, this problem can largely be circumvented.
The same argument can be made for JS. If you and your co-developers follow the best practices in JS, this problem can largely be circumvented. By following best practices, you can ensure that everyone on your team is on the same page, which makes it easier to avoid errors and manage code changes.
In my eyes, JSDoc is more verbose compared to TS.
But in the case of using TSDoc with TS, you will end up with the same verbosity.
in many cases properly named variables can easily replace JSDoc comments.
This opens up a whole new debate: Proper Naming Convention Vs Code Documentation. But, Agree with you on this point.
5. Lack of Compatibility.
You points are valid over here. But, sometimes it can cause headaches. It is my fault that I didn't provide a reproducible example cause it's was too complicated and I don't have the rights to share it.
6. Low Productivity.
Frankly, sometimes I have the feeling I only write types for the compiler's sake.
This!
And I would always choose taking weeks longer for the initial release than spending months patching up my mess.
So, it is clear that it will lower your productivity, ok.
All of my previous Hackathon submissions, after learning the language, are written at least partially in TS. One even won me a grand prize. And I'm happy for the static types, because now I can keep developing on it without reviewing the whole codebase.
I think your experience is great and I'm happy you had success with using TypeScript. However, I disagree with using it in a time-constrained environment such as a one-day hackathon. The learning curve for TypeScript is quite steep and there's not enough time to came up with a prototype to take full advantage of its benefits.
7. False Promises.
If this is true, I have a misconception of the language. Is this your personal opinion or has this been stated by one of the core development team? If so, can you please provide a source for this statement?
If it doesn't solve JavaScript problems, then what is the point of inventing this language? I would say, it is not 100% valid, yet still a speculative argument.
The goal of TypeScript is to be a static typechecker for JavaScript programs.
The absence of a static type checker is a problem in JS, isn't it?
14. Lack of Performance.
Performance can indeed become a problem during development when using TS in Node.js using ts-node or nodemon.
This!
I see your points, and I understand where you're coming from. However, I would argue that you would still resort to TS/JSDoc anyway to document your TS code. Have a look at the core TS code and let me know. This begs the question: why use TypeScript in the first place? Know what I am saying?
I'm a selftaught (web) developer. On sunny days, you can find me hiking through the Teutoburg Forest, on rainy days coding or with a good fiction novel in hand.
See. You are providing already existing statically typed languages. Why bother creating a new one?
I think you're trying to compare apples to pears. Have you ever tried to write a React app using C#?
Regarding 'Why bother creating a new one?'. Because competition is good for innovation. I don't see competing standards as a bad thing. Because they compete to be the best, hence they keep improving. And from my minor perspective, TS is superior to JSDoc in terms of static type checking in every way.
JavaScript has become one of the most popular programming languages in the world because it gives us the freedom to write code without being constrained by static types.
Types in Typescript are optional
However, I think it's really hard for developers who are just starting out using the language.
Can you verify this? I found it hard because I never worked with static types before. And I would argue that the hardest part is to learn the syntax - which is true for all other languages. I think it's really hard for developers who are just starting using ANY language.
JSDoc enforces no strict types.
In VSCode, just enable it in file > preferences > settings > search for "checkjs"
That's no strict type checking because there's no compiler, just the Typescript language server. (Yes, even JSDoc uses Typescript under the hood, hooray for standards.)
JSDoc is verbose
How about using TSDoc with TS code?
Looks pretty verbose too. Perhaps I should have formulated: 'JSDoc to be looks more verbose than Typescript based on the lines of text added to a particular file'.
What? Are we talking about semantic checking NOT a benefit?
I'm not sure how you got that idea tbf. I stated that JSDoc has no compiler and TS does.
With 'You can type your whole codebase with JSDoc without any other benefit but the comments in your IDE.', I meant:
You can ship incorrectly typed code (could have errors, could have none)
JSDoc will not stop you, because there is no compilation step involved.
If there is an error due to wrong type expectations, you might not even notice it in the application itself. I love Javascript's anarchistic approach to dynamic types, it's what opened the gate to programming to me. At the same time, I've seen horrible crimes being comitted using Vanilla JS - Syntax in non-strict mode.
Imagine you have a shop system. A customer orders a t-shirt and a jacket. Your junior dev has presented a logic to calculate shipping fee based on the total amount of items.
You can probably spot the mistake right away? Let's to the same, this time typed out:
typeItem={name:string,price:string,currency:string;qty:number}constshirt={name:"Shirt",price:"19.99",currency:"EUR",qty:"1"}constjacket={name:"Jacket",price:"59.99",currency:"EUR",qty:"1"}constcart:Item[]=[shirt,jacket];constshippingFeePerItem=3.99;functioncalcShippingFee(cart):number{consttotalItemCount=cart.reduce((previous,current)=>{returnprevious+current.qty},0)returntotalItemCount*shippingFeePerItem}console.log(calcShippingFee(cart))// Still 43.89
Now remove the quotation marks from around the qty property of both items, pat your junior on the shoulder and say "We've all been there".
And yes, you could have achieved the same behavior with JSDoc & The JS/TS check. Just like your junior could have ignored this mistake and ship the whole thing, causing havoc at checkout. Because no compiler could stop him.
Nice to meet you, ma fren 🫡. Sorry, I ain't DEVing that much ✍️ , primarily due to the nature of maintaining Open Source projects 👷, while also gigging 💰. Anyways, stay humble like a bumblebee 🐝.
Regarding 'Why bother creating a new one?'. Because competition is good for innovation. I don't see competing standards as a bad thing.
I completely agree; competition is not a bad thing. In fact, it can be quite healthy and motivating. However, I think the key point here is that the mentality has shifted over the years from static languages to more flexible, dynamic ones. And now we are seeing a move back to static languages. This begs the question of why we are now moving backward. Transitioning from dynamically typed language to statically typed ones?
I think it's important to keep in mind that while competition is definitely a good thing, we also need to be careful not to get too caught up in it. There's a fine line between healthy competition and unhealthy obsession, and it's important to make sure we don't cross that line.
TS is superior to JSDoc in terms of static type checking in every way.
Still can't see why it is superior.
Can you verify this? I found it hard because I never worked with static types before. And I would argue that the hardest part is to learn the syntax - which is true for all other languages. I think it's really hard for developers who are just starting using ANY language.
Yep.
'JSDoc to be looks more verbose than Typescript based on the lines of text added to a particular file'.
How? Here is a good comparison between the two.
I stated that JSDoc has no compiler
As mentioned in the article, This is intentional, as having a compiler would slow down the development process. JSDoc is intended to be used as a documentation tool, and not as a means of adding code generation or validation. Still, it is possible to use JSDoc for these purposes.
You can ship incorrectly typed code (could have errors, could have none)
JSDoc will not stop you, because there is no compilation step involved.
I would argue that JSDoc's lack of a compiler can be seen as a positive thing. The need for a compiler would slow down the development process, and JSDoc's focus on documentation over compilation means that it can be used more quickly and easily.
I love Javascript's anarchistic approach to dynamic types, it's what opened the gate to programming to me.
Same.
I've seen horrible crimes being comitted using Vanilla JS - Syntax in non-strict mode.
Again, for forgiveness' sake. If there are good QA / development philosophies followed, we are good.
And yes, you could have achieved the same behavior with JSDoc & The JS/TS check.
That's the main point.
Just like your junior could have ignored this mistake and ship the whole thing, causing havoc at checkout. Because no compiler could stop him.
It is true that mistakes are inevitable, but it is also true that when the right DevOps philosophy is followed and implemented, it helps to prevent and minimize the chances of making any mistakes. The key thing here is to have an understanding of what works for your team and business and then build a reliable system around it.
This could include setting up guidelines for code review, automated tests, deployment processes, etc., to ensure that only quality code makes its way into production. Additionally, having a correct monitoring strategy in place can help you detect problems in the system before they become too big and cause disruption.
The moral of the story is that while dynamic languages offer flexibility, static typing gives us safety and security when coding. So although moving from statically typed languages to dynamic languages may feel like a step backward, in reality, it is a step forward in terms of overall efficiency and productivity.
I'm a selftaught (web) developer. On sunny days, you can find me hiking through the Teutoburg Forest, on rainy days coding or with a good fiction novel in hand.
I think we've reached a sweet spot in our discussion, so I'd like to finish with one last comment.
The key thing here is to have an understanding of what works for your team and business and then build a reliable system around it.
Additionally, having a correct monitoring strategy in place can help you detect problems in the system before they become too big and cause disruption.
This sounds a lot like having an additional step in between development and production. Like compilation.
You argued that a compiler slows development down. Then I'd say: Let's ditch QA altogether, like that we reduce our time to market by another 25%. Also, let's ditch all modern frameworks and write monolithic CSS again. Na, why bother writing classes? Inline CSS is the way, because with our IDE, we can do a mass-replace anyway. Or let AI handle the complex stuff (this seems like a real alternative by now).
Your code example gave me the shivers btw. I've seen a dev in my previous org naming all function arguments param1, param2, param3, ... . That went up to 12 args in one function.
Your comments seem a bit redundant and cover up for missing function context, so allow me to add another example here in TS, without the verbosity:
By proper naming, you can actually reduce the amount of comments you need. This is a simple example, so let me give you another in TS and JS.
The following code will read a file from a local machine. It can read it in three different ways: Buffer, JSON or String.
importfsfrom'fs/promises';importpathfrom'path';constsomePath=path.join(__dirname,'../settings.json');asyncfunctionreadFile(filePath:string,readAs:'string'|'buffer'|'json'):Promise<string|Buffer>{constfileBuffer=awaitfs.readFile(filePath);if(readAs==='string'){returnBuffer.from(fileBuffer).toString('utf-8');}if(readAs==='json'){returnJSON.parse(Buffer.from(fileBuffer).toString('utf-8'));}if(readAs==='buffer'){returnfileBuffer;}thrownewError(`Cannot read settings as ${readAs}. Valid types are 'string', 'buffer', 'json'`);}readFile(somePath,'string');readFile(somePath,'buffer');readFile(somePath,'json');
Here's what I came up with in Javascript applying the same logic as you did above:
importfsfrom'fs/promises';importpathfrom'path'constp=path.join(__dirname,'../settings.json')/**
* @description Reads a file from the local file system.
* @param {string} p The path from which to read the file
* @param {'json' | 'string' | 'buffer'} r The type as which to read the file
* @returns {Promise<string | Buffer>} The content of the file
*/asyncfunctionjsRead(p,r){constfb=awaitfs.readFile(p);if(r==="string"){returnBuffer.from(fb).toString('utf-8');}if(r==="json"){returnJSON.parse(Buffer.from(fb).toString('utf-8'));}if(r==="buffer"){returnfb;}thrownewError(`Cannot read settings as ${r}. Valid types are 'string', 'buffer', 'json'`);}jsRead(p,'string');jsRead(p,'buffer');jsRead(p,'json');
The only thing that changed is that I moved all the information out of the function and put it above, creating 4 additional lines of code I could have saved.
While this example is very specific, you can see an increase of ~12% in textual content (lines and signs)
29 lines became 33
698 signs became 793
In a real project, this value might be significantly smaller, but If I can save 4 or 5% in a project with thousands of lines of code while increasing readability AND have static type checks AND I have a DevOps pipeline in place anyway, I'd be willing to pay the price of using a compiler.
Nice to meet you, ma fren 🫡. Sorry, I ain't DEVing that much ✍️ , primarily due to the nature of maintaining Open Source projects 👷, while also gigging 💰. Anyways, stay humble like a bumblebee 🐝.
This sounds a lot like having an additional step in between development and production. Like compilation.
I would say yes, but it is not necessarily the case. A compilation is not necessary as an additional step between development and production. Someone may argue that TDD could be this step.
Your code example gave me the shivers btw. I've seen a dev in my previous org naming all function arguments param1, param2, param3, ... . That went up to 12 args in one function.
I think you missed the point I was trying to make. I'm not arguing about the naming conventions, I'm just showing how the function definition line becomes so fat/bloated without using JSDoc. I mean, have a look at this line:
Instead, JSDoc offers the most convenient way for both documentation and type checking (with CheckJS).
/**
* @param {number} first - The first number.
* @param {number} second - The second number.
* @param {number} third - The third number.
* @param {number} fourth - The fourth number.
* @param {number} fifth - The fifth number.
* @returns {number} - the result.
*/functionjsCreateSum(first,second,third,fourth,fifth)
This will make your function easier to read without the need to scroll horizontally. So, I think with JSDoc, it's arguably much easier to understand what's going on.
By proper naming, you can actually reduce the amount of comments you need.
This opens up a whole new debate: Code Documentation VS Good Naming Convention.
The following code will read a file from a local machine. It can read it in three different ways: Buffer, JSON or String.
But the first example doesn't have documentation. If you use TSDoc, you will end up with the same number of lines in both examples.
I'm a selftaught (web) developer. On sunny days, you can find me hiking through the Teutoburg Forest, on rainy days coding or with a good fiction novel in hand.
I apologize should I have mislead you, but my words were not meant to be kind, but critital. Yes, you did a lot of research and I appreciate the article. That doesn't mean that I agree with everything.
However, I would argue that you would still resort to TS/JSDoc anyway to document your TS code
What gave you this idea?
The repository you linked includes a ts declaration file for interfaces. In this case, JSDoc is used to provide additional information inside IDEs or text editors. Try and type the following in your IDE:
[].find
Hover over find. You'll see the JSDoc comments are equal to the text content. Also, the declaration file is for vanilla ES6 Javascript features and tbf I'm happy for every piece of documentation I can get.
There are more examples. Projects like Deno also ship fully commented interface libraries because they're very useful to develop with:
There are two answers, one for this case and a generic one.
For a code library like this, I am happy when people do proper documentation. The documentation happens to be part of the code. And it integrates well into my IDE, too. Sounds good.
For all other cases
Using JSDoc provides me the neat help text you see when hovering methods. It's also useful to automatically generate static docs which are always equal to the code suggestions in my codebase
Using Typescript provides code suggestions & helps me make my project more robust. There is a VSCode setting that includes static type checks for JS + JSDoc, but since the compilation step is missing, I do not have the chance to enforce this rule.
The latter is, again, especially important when working in teams. And I don't have to use JSDoc to provide these small popups in the IDE, normal comments are perfectly sufficient.
By now, I see a lot of projects that use the monorepos style written in TS. Because while not essential, it helps to prevent code rigidity. Below are examples for three robust and famous frameworks with a huge codebase and many team members:
Nice to meet you, ma fren 🫡. Sorry, I ain't DEVing that much ✍️ , primarily due to the nature of maintaining Open Source projects 👷, while also gigging 💰. Anyways, stay humble like a bumblebee 🐝.
I apologize should I have mislead you, but my words were not meant to be kind, but critital. Yes, you did a lot of research and I appreciate the article. That doesn't mean that I agree with everything.
I meant not in an insulting way. Criticism is always welcome.
JSDoc is used to provide additional information inside IDEs or text editors.
Using Typescript provides code suggestions & helps me make my project more robust.
Using JSDoc provides me the neat help text you see when hovering methods.
That's the whole point. Why using TS in the first place and TSDoc with TS when you can use JSDoc for type-checking, documentation, and code suggestions in JS?
I'm a selftaught (web) developer. On sunny days, you can find me hiking through the Teutoburg Forest, on rainy days coding or with a good fiction novel in hand.
I think you're answering this question with a few of your article's points.
TS enforces strict types and invites developers from other statically typed, OOP - based languages, like Java and C#, to participate in projects. With the static types they already know and the flexibility of Javascript's core features
TS is actually (mainly) intuitive syntax (once you get used to it).
Compared to Javascript, TS reduces tech debt on the short & long run. It makes mono-repositories easier to maintain & libraries and modules public APIs less prone to errors. Because you have a compiler to convince that your logic is sound, with all pros and cons that brings.
Now you could argue: Well, all of this goes for JSDoc, too, doesn't it?
Yes and no. Because
JSDoc enforces no strict types. There is Javadoc, but I've seen it used very rarely in the wild, while Java Types are everywhere
JSDoc is verbose and not part of the code, but a textual extension. I don't find typing out function arguments very intuitive. Not now, probably not ever. I keep forgetting how to do a proper @typedef every other time and I cannot declare complex types. Also, I find generics in JSDoc rather ugly.
(maybe the most important part): JSDoc has no compiler. You can type your whole codebase with JSDoc without any other benefit but the comments in your IDE.
Nice to meet you, ma fren 🫡. Sorry, I ain't DEVing that much ✍️ , primarily due to the nature of maintaining Open Source projects 👷, while also gigging 💰. Anyways, stay humble like a bumblebee 🐝.
TS enforces strict types and invites developers from other statically typed, OOP - based languages, like Java and C#, to participate in projects. With the static types they already know and the flexibility of Javascript's core features
See. You are providing already existing statically typed languages. Why bother creating a new one? Oh, I forget, it is just another standard.
JavaScript has become one of the most popular programming languages in the world because it gives us the freedom to write code without being constrained by static types. People seem to forget that.
TS is actually (mainly) intuitive syntax (once you get used to it).
For me, it is. However, I think it's really hard for developers who are just starting out using the language. There are SO many questions and common pitfalls that can trip them up. It's scary!
JSDoc enforces no strict types.
In VSCode, just enable it in file > preferences > settings > search for "checkjs"
And Bam! You got semantic checking enabled (kind of static typing).
JSDoc is verbose
How about using TSDoc with TS code?
(maybe the most important part): JSDoc has no compiler. You can type your whole codebase with JSDoc without any other benefit but the comments in your IDE.
What? Are we talking about semantic checking NOT a benefit?
Just a hobbyist programmer with an eye on new technologies. Currently helping Quasar and NestJS Frameworks, because....well.....because they're awesome! :-)
JavaScript has become one of the most popular programming languages in the world because it gives us the freedom to write code without being constrained by static types. People seem to forget that.
This is SO wrong. JavaScript is as ubiquitous as it is because of browsers and the Internet. Had JavaScript not been the language used to make HTML interactive and there would be some other language, then we'd all be using that more than likely. The popularity of JavaScript today has NOTHING to do with what JavaScript is as a language in the end. I'd also add that JavaScript as a programming language only really became significant in 2010, when the first Node version came out, allowing JavaScript to be used for both frontend and backend applications. It doesn't matter either. The point being, I think we can agree, JavaScript is the #1 web application language right now.
Now, my correction also doesn't make your point moot. JavaScript can and does give us the freedom to write code without static types. However, once a code base gets to a certain size, this freedom becomes a very common footgun and that is why TypeScript became even a thing and why it is growing fast. Because teams of developers need type safety.
I'm not going to go into your litany of reasons not to use TypeScript. I'll say for sure, you are swimming against the stream that is gaining in strength. Instead of complaining with a list of shaky reasons to dislike TypeScript, put your energy into supporting making the language better, because, JavaScript's and TypeScript's ubiquity isn't going to stop any time soon. It is all here to stay. And if I were you, I'd want to make waves by making the language better, instead of looking like the one whiny fish who thinks the stream is going in the wrong direction and ending up bumping heads with the other fish going that same direction. It's counterproductive for us all.
Scott
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
First off, you've obviously dedicated a lot of time and research into this article. I found several very valid and well-thought points, some which I do not agree with and a few that I find simply incorrect (= could not cross-verify anywhere).
TL:DR - I have added a few counter arguments for each of the points of this post, all of which are very subjective. I love JSDoc, especially in environments that do not support TS. Some of your points, in my eyes, might be a bit misleading to devs getting started with the language. You're invited to disagree with each of them, hence the tone.
1. The Learning Curve.
As you state, using TS or not heavily depends on the use case. Given you're working on an enterprise-grade project with several developers, comparing the cost of learning against the cost of later maintenance, I find this no valid argument against Typescript.
Quite the opposite - since it's hard to learn, it's a valuable asset for your portfolio. Learning TS increases your net worth and distinguishes you from other developers.
2. Strict Type Checking System.
The example you provide is literally a type-only bubble sort in TS. I do not find it to be a practical example of static type checks. Applying this principle to anything but snippets feels like writing the whole codebase in a
@typesdirectory.I agree with your statement that complex types are, well, complex. That's why they're being used. Compared to languages like Rust or Java, you do not have to type your whole project. If types are too complex, you're free to leave them out.
3. Verbosity And Lack of Readability.
True, large TS codebases are a mess. Just from my experience, it's not the types per se that cause havoc, but the way they're named and maintained. If you and your co-devs handle them properly and prevent them from rotting, this problem can largely be circumvented.
Regarding one of your alternative solutions: In my eyes, JSDoc is more verbose compared to TS. You can see it in your own example - in many cases properly named variables can easily replace JSDoc comments.
4. Lack Of Intuitive Syntax
See point 1.
5. Lack of Compatibility.
The example you describe is not a problem with the language. Why should I ditch the language if the environment does not support it? That feels like saying 'I ditch Python because it does not run in my browser console' in 2015. This problem led to a great innovation called Pyscript.
6. Low Productivity.
Frankly, sometimes I have the feeling I only write types for the compiler's sake. But writing types, enums and interfaces forces me to think through by data structures and optimise on the go. And I would always choose taking weeks longer for the initial release than spending months patching up my mess.
I do want it because I'll spend only the weekend writing on the code. And I'll have forgotten most of the data structures in the time between. Because I am lazy and do not document a lot (sometimes ChatGPT does that for me), I'm happy seeing my previous thoughts neatly formatted as interfaces waiting for me to come back.
All of my previous Hackathon submissions, after learning the language, are written at least partially in TS. One even won me a grand prize. And I'm happy for the static types, because now I can keep developing on it without reviewing the whole codebase.
Using Javascript is great because of the short time-to-market, but in my eyes, it's largely outweighed by maintenance costs for enterprise grade apps.
7. False Promises.
If this is true, I have a misconception of the language. Is this your personal opinion or has this been stated by one of the core development team? If so, can you please provide a source for this statement?
For me TS is pretty much this:
Source: typescriptlang.org/docs/handbook/i... , second paragraph, last sentence.
8. Lack of Flexibility.
See points 2, 6 and 7
I don't think TS limits my creativity. All types are optional, nothing prevents me from typing everything with
any. But I find it more elegant and more responsible towards my customers to write robust code. With great power comes great responsibility, after all.9. Giant Corporation Abuse.
Yes and no.
Fortunately, Microsoft is not solely run by Steve Ballmer. Of course they used to doom Open Source, until they figured how to capitalise on it. And now, there's software like this:
And to provide a more recent opinion on Windows <-> Linux: cloudblogs.microsoft.com/windowsse...
10. Clever Devs Abuse.
This happens in Javascript too & does not really count as a reason to ditch the language
11. Not A JS Superset.
I am unsure how to respond to this statement and the example you provide properly. In general, you're not wrong. Since TS uses static types, types must be known at compile time. This also goes for your example. Yet as stated in point 8, I see no problem in this, but an opportunity to make my code more robust:
12. Slower Compile Time + 13. Additional Transpilation Step
True, that's the price you pay.
14. Lack of Performance.
Usually, you do not ship TS code to production.
Performance can indeed become a problem during development when using TS in Node.js using ts-node or nodemon. In the frontend, Vite does a good job at solving performance issues.
15. Writing Unit Tests.
I find it even easier because all my types are already declared and, if I did a good job, count for tests and the software.
And where's the problem? I would want my co-dev to document a change like this somewhere.
I still remember an upgrade from formidable v2 -> v3, where a single property name changed and I spent a whole week figuring this out (in a JS codebase) because the app would keep crashing. Okay, I haven't read the breaking changes in the log, but I was still quite upset about such a minor change making such a huge impact.
16. Types Are Not That Useful.
See points 1-15
17. Heavier Tech Debt.
Sure there are madman PMs changing the architecture halfway through the project. But that's not technical debt, it's poor planning.
Also:
Boy am I glad the concept of static typing is language agnostic.
Thank you so much for your kind words!Oh thanks! I'm glad you appreciated all the work that went into this article. It's true that a lot of research and time went into it, and I'm pleased to hear that it was worth it. I'm glad that it resonated with you. Thank you for taking the time to read it.This!
Let's do this!
1. The Learning Curve.
Of course, I mean if you want to pay me xxx$ , I can learn whatever the heck you wanted. That's not the point. As stated in the article, the main point is:
2. Strict Type Checking System.
Agree with this.
3. Verbosity And Lack of Readability.
This!
The same argument can be made for JS. If you and your co-developers follow the best practices in JS, this problem can largely be circumvented. By following best practices, you can ensure that everyone on your team is on the same page, which makes it easier to avoid errors and manage code changes.
But in the case of using TSDoc with TS, you will end up with the same verbosity.
This opens up a whole new debate: Proper Naming Convention Vs Code Documentation. But, Agree with you on this point.
5. Lack of Compatibility.
You points are valid over here. But, sometimes it can cause headaches. It is my fault that I didn't provide a reproducible example cause it's was too complicated and I don't have the rights to share it.
6. Low Productivity.
This!
So, it is clear that it will lower your productivity, ok.
I think your experience is great and I'm happy you had success with using TypeScript. However, I disagree with using it in a time-constrained environment such as a one-day hackathon. The learning curve for TypeScript is quite steep and there's not enough time to came up with a prototype to take full advantage of its benefits.
7. False Promises.
If it doesn't solve JavaScript problems, then what is the point of inventing this language? I would say, it is not 100% valid, yet still a speculative argument.
The absence of a static type checker is a problem in JS, isn't it?
14. Lack of Performance.
This!
I see your points, and I understand where you're coming from. However, I would argue that you would still resort to TS/JSDoc anyway to document your TS code. Have a look at the core TS code and let me know. This begs the question: why use TypeScript in the first place? Know what I am saying?
I think you're trying to compare apples to pears. Have you ever tried to write a React app using C#?
Regarding 'Why bother creating a new one?'. Because competition is good for innovation. I don't see competing standards as a bad thing. Because they compete to be the best, hence they keep improving. And from my minor perspective, TS is superior to JSDoc in terms of static type checking in every way.
Types in Typescript are optional
Can you verify this? I found it hard because I never worked with static types before. And I would argue that the hardest part is to learn the syntax - which is true for all other languages. I think it's really hard for developers who are just starting using ANY language.
That's no strict type checking because there's no compiler, just the Typescript language server. (Yes, even JSDoc uses Typescript under the hood, hooray for standards.)
Looks pretty verbose too. Perhaps I should have formulated: 'JSDoc to be looks more verbose than Typescript based on the lines of text added to a particular file'.
I'm not sure how you got that idea tbf. I stated that JSDoc has no compiler and TS does.
With 'You can type your whole codebase with JSDoc without any other benefit but the comments in your IDE.', I meant:
If there is an error due to wrong type expectations, you might not even notice it in the application itself. I love Javascript's anarchistic approach to dynamic types, it's what opened the gate to programming to me. At the same time, I've seen horrible crimes being comitted using Vanilla JS - Syntax in non-strict mode.
Imagine you have a shop system. A customer orders a t-shirt and a jacket. Your junior dev has presented a logic to calculate shipping fee based on the total amount of items.
You can probably spot the mistake right away? Let's to the same, this time typed out:
Now remove the quotation marks from around the
qtyproperty of both items, pat your junior on the shoulder and say "We've all been there".And yes, you could have achieved the same behavior with JSDoc & The JS/TS check. Just like your junior could have ignored this mistake and ship the whole thing, causing havoc at checkout. Because no compiler could stop him.
I completely agree; competition is not a bad thing. In fact, it can be quite healthy and motivating. However, I think the key point here is that the mentality has shifted over the years from static languages to more flexible, dynamic ones. And now we are seeing a move back to static languages. This begs the question of why we are now moving backward. Transitioning from dynamically typed language to statically typed ones?
I think it's important to keep in mind that while competition is definitely a good thing, we also need to be careful not to get too caught up in it. There's a fine line between healthy competition and unhealthy obsession, and it's important to make sure we don't cross that line.
Still can't see why it is superior.
Yep.
How? Here is a good comparison between the two.
As mentioned in the article, This is intentional, as having a compiler would slow down the development process. JSDoc is intended to be used as a documentation tool, and not as a means of adding code generation or validation. Still, it is possible to use JSDoc for these purposes.
I would argue that JSDoc's lack of a compiler can be seen as a positive thing. The need for a compiler would slow down the development process, and JSDoc's focus on documentation over compilation means that it can be used more quickly and easily.
Same.
Again, for forgiveness' sake. If there are good QA / development philosophies followed, we are good.
That's the main point.
It is true that mistakes are inevitable, but it is also true that when the right DevOps philosophy is followed and implemented, it helps to prevent and minimize the chances of making any mistakes. The key thing here is to have an understanding of what works for your team and business and then build a reliable system around it.
This could include setting up guidelines for code review, automated tests, deployment processes, etc., to ensure that only quality code makes its way into production. Additionally, having a correct monitoring strategy in place can help you detect problems in the system before they become too big and cause disruption.
The moral of the story is that while dynamic languages offer flexibility, static typing gives us safety and security when coding. So although moving from statically typed languages to dynamic languages may feel like a step backward, in reality, it is a step forward in terms of overall efficiency and productivity.
I think we've reached a sweet spot in our discussion, so I'd like to finish with one last comment.
This sounds a lot like having an additional step in between development and production. Like compilation.
You argued that a compiler slows development down. Then I'd say: Let's ditch QA altogether, like that we reduce our time to market by another 25%. Also, let's ditch all modern frameworks and write monolithic CSS again. Na, why bother writing classes? Inline CSS is the way, because with our IDE, we can do a mass-replace anyway. Or let AI handle the complex stuff (this seems like a real alternative by now).
Your code example gave me the shivers btw. I've seen a dev in my previous org naming all function arguments param1, param2, param3, ... . That went up to 12 args in one function.
Your comments seem a bit redundant and cover up for missing function context, so allow me to add another example here in TS, without the verbosity:
By proper naming, you can actually reduce the amount of comments you need. This is a simple example, so let me give you another in TS and JS.
The following code will read a file from a local machine. It can read it in three different ways: Buffer, JSON or String.
Here's what I came up with in Javascript applying the same logic as you did above:
The only thing that changed is that I moved all the information out of the function and put it above, creating 4 additional lines of code I could have saved.
While this example is very specific, you can see an increase of ~12% in textual content (lines and signs)
In a real project, this value might be significantly smaller, but If I can save 4 or 5% in a project with thousands of lines of code while increasing readability AND have static type checks AND I have a DevOps pipeline in place anyway, I'd be willing to pay the price of using a compiler.
I would say yes, but it is not necessarily the case. A compilation is not necessary as an additional step between development and production. Someone may argue that TDD could be this step.
I think you missed the point I was trying to make. I'm not arguing about the naming conventions, I'm just showing how the function definition line becomes so fat/bloated without using JSDoc. I mean, have a look at this line:
Instead, JSDoc offers the most convenient way for both documentation and type checking (with CheckJS).
This will make your function easier to read without the need to scroll horizontally. So, I think with JSDoc, it's arguably much easier to understand what's going on.
This opens up a whole new debate: Code Documentation VS Good Naming Convention.
But the first example doesn't have documentation. If you use TSDoc, you will end up with the same number of lines in both examples.
I apologize should I have mislead you, but my words were not meant to be kind, but critital. Yes, you did a lot of research and I appreciate the article. That doesn't mean that I agree with everything.
What gave you this idea?
The repository you linked includes a ts declaration file for interfaces. In this case, JSDoc is used to provide additional information inside IDEs or text editors. Try and type the following in your IDE:
Hover over
find. You'll see the JSDoc comments are equal to the text content. Also, the declaration file is for vanilla ES6 Javascript features and tbf I'm happy for every piece of documentation I can get.There are more examples. Projects like Deno also ship fully commented interface libraries because they're very useful to develop with:
github.com/denoland/deno/blob/421e...
There are two answers, one for this case and a generic one.
For a code library like this, I am happy when people do proper documentation. The documentation happens to be part of the code. And it integrates well into my IDE, too. Sounds good.
For all other cases
The latter is, again, especially important when working in teams. And I don't have to use JSDoc to provide these small popups in the IDE, normal comments are perfectly sufficient.
By now, I see a lot of projects that use the monorepos style written in TS. Because while not essential, it helps to prevent code rigidity. Below are examples for three robust and famous frameworks with a huge codebase and many team members:
I meant not in an insulting way. Criticism is always welcome.
That's the whole point. Why using TS in the first place and TSDoc with TS when you can use JSDoc for type-checking, documentation, and code suggestions in JS?
I think you're answering this question with a few of your article's points.
TS enforces strict types and invites developers from other statically typed, OOP - based languages, like Java and C#, to participate in projects. With the static types they already know and the flexibility of Javascript's core features
TS is actually (mainly) intuitive syntax (once you get used to it).
Compared to Javascript, TS reduces tech debt on the short & long run. It makes mono-repositories easier to maintain & libraries and modules public APIs less prone to errors. Because you have a compiler to convince that your logic is sound, with all pros and cons that brings.
Now you could argue: Well, all of this goes for JSDoc, too, doesn't it?
Yes and no. Because
JSDoc enforces no strict types. There is Javadoc, but I've seen it used very rarely in the wild, while Java Types are everywhere
JSDoc is verbose and not part of the code, but a textual extension. I don't find typing out function arguments very intuitive. Not now, probably not ever. I keep forgetting how to do a proper @typedef every other time and I cannot declare complex types. Also, I find generics in JSDoc rather ugly.
(maybe the most important part): JSDoc has no compiler. You can type your whole codebase with JSDoc without any other benefit but the comments in your IDE.
See. You are providing already existing statically typed languages. Why bother creating a new one? Oh, I forget, it is just another standard.
JavaScript has become one of the most popular programming languages in the world because it gives us the freedom to write code without being constrained by static types. People seem to forget that.
For me, it is. However, I think it's really hard for developers who are just starting out using the language. There are SO many questions and common pitfalls that can trip them up. It's scary!
In VSCode, just enable it in file > preferences > settings > search for "checkjs"
And Bam! You got semantic checking enabled (kind of static typing).
How about using TSDoc with TS code?
What? Are we talking about semantic checking NOT a benefit?
This is SO wrong. JavaScript is as ubiquitous as it is because of browsers and the Internet. Had JavaScript not been the language used to make HTML interactive and there would be some other language, then we'd all be using that more than likely. The popularity of JavaScript today has NOTHING to do with what JavaScript is as a language in the end. I'd also add that JavaScript as a programming language only really became significant in 2010, when the first Node version came out, allowing JavaScript to be used for both frontend and backend applications. It doesn't matter either. The point being, I think we can agree, JavaScript is the #1 web application language right now.
Now, my correction also doesn't make your point moot. JavaScript can and does give us the freedom to write code without static types. However, once a code base gets to a certain size, this freedom becomes a very common footgun and that is why TypeScript became even a thing and why it is growing fast. Because teams of developers need type safety.
I'm not going to go into your litany of reasons not to use TypeScript. I'll say for sure, you are swimming against the stream that is gaining in strength. Instead of complaining with a list of shaky reasons to dislike TypeScript, put your energy into supporting making the language better, because, JavaScript's and TypeScript's ubiquity isn't going to stop any time soon. It is all here to stay. And if I were you, I'd want to make waves by making the language better, instead of looking like the one whiny fish who thinks the stream is going in the wrong direction and ending up bumping heads with the other fish going that same direction. It's counterproductive for us all.
Scott