How to define Objects with type definitions in JSDoc comments

When it comes to writing clear and easily understandable JavaScript code, JSDoc comments are an essential tool. Properly documenting your code not only makes it easier for other developers to understand what you've written, but also helps prevent future bugs and make code maintenance more accessible. One of the most important aspects of writing JSDoc comments is correctly defining your types. In this article, we'll explore the benefits and best practices of using type definitions instead of the {Object} type when defining objects in JSDoc comments.

The {Object} type is a generic type that can be used to describe any object in JavaScript. However, while it may seem convenient to use {Object} to define your object types in JSDoc comments, this practice can lead to confusion and ambiguity. By specifying only {Object}, you're not providing enough information for other developers to understand the shape of the object. It's also worth noting that using the {Object} type will not enable your IDE to offer code completion for object properties, which can also impact productivity.

Instead of relying on the {Object} type, it's essential to define types for your objects that explicitly describe their properties and types. For example, instead of defining an object with simply {Object}, you could define it like so:

/**
* @typedef {Object} User
* @property {string} firstName - The user's first name.
* @property {string} lastName - The user's last name.
* @property {number} age - The user's age.
* @property {string} email - The user's email address.
*/

By defining a type, you're providing additional context that can help other developers understand how to interact with your code more clearly. In this example, we've defined a type called User that has four properties with explicit types.

Another benefit of explicitly defining types is that you can reuse them in other parts of your code. For example, imagine you're working on a project that uses a lot of objects with similar properties. Instead of defining each of them separately, you can define a single type and reuse it throughout your codebase.

Using type definitions in this way can also help catch errors earlier. If you accidentally try to use a property that isn't defined in a type, your IDE will alert you to that mistake, and you can correct it before running the code.

IDE autocomplete

For example, if we don't define a schema and we just say that the variable is just an {Object}, our IDE will not know what this Object contains, so it will not be able to enable the autocompletition, like the following:

But instead if you use a type definition, then the IDE will understand what your Object contains and how to react to it, similar to how you expect to see with TypeScript for example, as you can see here:

Conclusions

In conclusion, while it may seem convenient to use the {Object} type in JSDoc comments, it's worth taking the time to define your own specific types. By using type definitions, you can provide more context for other developers, improve code readability and catch errors earlier in the development process.