JavaScript is a versatile and dynamic programming language that allows developers to build a wide range of applications. However, its dynamic nature can sometimes lead to errors and bugs that are challenging to detect during development. To address this, developers often turn to type annotations to provide clarity and ensure code correctness. Two popular approaches for adding type annotations to JavaScript code are JSDoc and TypeScript.
Understanding JSDoc
JSDoc is a comment syntax that can be used to annotate JavaScript code with type information. JSDoc annotations are not enforced by the JavaScript compiler, but they can be used by linters and IDEs to provide static type checking.
JSDoc annotations are written in the form of @tag, where the tag specifies the type or purpose of the annotated element. For example:
/**
* @type {string}
*/
const randomestring = "42";
JSDoc also supports more complex type annotations, such as custom objects, arrays, and function signatures.
/**
* @typedef {Object} Foo
* @property {string} bar
* @property {number} nda
*/
/**
* @type {Foo[]}
*/
const randomObj = [
{ bar: "the answer to life, universe and everything", nda: 42 },
{ bar: "random string", nda: 25 }
];
/**
* @param {Foo} obj
* @returns {string}
*/
function randomFunction(obj) {
return `${obj[0].bar} is ${obj[0].nda}.`;
}
Understanding TypeScript
TypeScript is JavaScript on steroids, adding optional static typing and other powerful features to the language. It allows developers to write a more strict form of JavaScript that helps write less error-prone code.
TypeScript needs to be compiled before it can be executed.
interface Foo {
bar: string;
nda: number;
}
const randomObj: Foo[] = [
{ bar: "the answer to life, universe and everything", nda: 42 },
{ bar: "random string", nda: 25 }
];
function randomFunction(obj: Foo): string {
return `${obj[0].bar} is ${obj[0].nda}.`;
}
JSDoc vs. TypeScript: Choosing the Right Approach
- Scenario #1 If you are using a framework like Next.js or Vue, there is always a build step. Therefore, you can ignore JSDoc and use TypeScript.
- JSDoc is a favorable option over TypeScript in scenarios where faster shipping is crucial due to the absence of compilation steps. Additionally, it proves beneficial when working with third-party JavaScript libraries without TypeScript support, handling small projects or scripts, and when incrementally adding type annotations to existing JavaScript codebases instead of rewriting them in TypeScript.
Top comments (4)
I have been working with strong typed languages for many years, and when I started to work with Javascript, I was expecting much trouble. Indeed, there are a lot of strange things in Javascript, but I was amazed that most of the trouble I had was not caused by this. Sometimes you need to add some more checks, but on the other hand, the sloppy type system gives you some freedom to do things really elegant.
Using typescript never really payd back for me, so finally most of the time I´m usiing plain Javascript.
If someday they would add a native optional type definition to Javascript, this would be very welcome. But it should give you the freedom to use types only when necessary, not everywhere
Could not agree more - there are times when it would really help, but I mostly find trying to convince TypeScript how to represent something I can just achieve naturally in JavaScript is a waste of time.
As a former C# programmer I am freed by the power of JavaScript, and find I don't crave the syntax of a strongly typed language when there are none of the benefits of performance granted by tightly defined types - just some type checking and a hell of a lot more symbols and code.
Maybe reducing the problem to type checks is just a bit too simplified. There are a lot of other differences to languages like C++ or Object Pascal:
In a compiled language all code is visited during compliation, so the compiler can find errors in code, that will be not or rarely be executed.
Encapsulation is much stronger, on module level and on class level. Modules are compiled independently from you main class, so they only get what you explicitly define. Classes in Pascal can additionally have a fine grained multi level contol of the visibility.
Modules usually need to define a complete interface, not just some identifiers. In Javascript, you do not know if an export names a function, a variable, constant or whatever. In Object Pascal you get a detailed description of what you export, the interface may even contain definitions of object structures or enumerables.
Structural definitions may not even come from a class, but from a parent class. This is often used to set some system wide standards. If some core definitions change, you will immediately get errors from all modules that use that definition. I´m not sure if test framework can provide the same level of reliability.
Developers in Javascrip can always bypass any stict encapsulation by using globalThis, and because it is so easy, they do. So there are a bunch of ways to add new or even exchange existing functions in the global scope that you cannot stop.
This is especially bad in JS, where identifiers may at least be a var, const or function. Using globalThis grants you access to the same identifiers without any restrictions. I´m not sure TS can stop this completely.
Typescript covers some of the aspects, but not all. So there is still a lot of space for unexpected errors in your code...
I normally do TypeScript and then annotate for descriptions using JSDoc. Bad? Good? Don't care?
As a developer, I appreciate self-explanatory API's.