Key Topics Outline:
- Documenting your code
- What is JSDoc?
- JSDoc in Typescript
- Use cases
Documenting your code
Software Development gives us the ability to create and design software systems for personal or business use. As a developer, it’s very easy to expect other developers to adapt to your code and understand exactly what your intentions are for a specific code block. However, we don’t usually allow ourselves to overlook this pretense due to our experience in developing in other code bases. From those experiences, we’ll use comments to ensure other developers are able to narrow down on why “Line 241” is throwing an error. These comments break down our intentions and intended functionality for these areas, which makes this important to have them in the first place. However, can we advance these comments further?
What is JSDoc?
JSDoc is a markup language for JavaScript that allows for documenting code in a standard format for readability and intellisense. With JSDoc in Visual Studio Code, you can easily begin documenting a specific function by typing “/**” and you’ll then be prompted for a JSDoc comment.
After entering into it, a specific template to the function below will be generated and allows you to fill in the function’s documentation.
With JSDoc in VS Code, we can utilize intellisense for our documentation on functions with ease. Here we have an example function “addTwoNums” that uses JSDoc for its documentation and breaks down the parameters and the required and expected return:
JSDoc in Typescript
Typescript allows us to specify types for inputs and outputs of functions, so it comes to be no surprise that JSDoc has further features to accommodate TypeScript. In our previous “addTwoNums” function we have our parameters to expect any type, which in the case of an adding function it should only add with integers.
We have access to the same documentation structure in vanilla javascript as well with JS Doc. Without requiring TypeScript, we can define the type that the function is expecting, even when we are dynamically assigning type.
Use Cases
Let’s review a few use cases to highlight the benefits of JSDoc compared to traditional documentation of functions through different degrees of quality. These examples represent our previously mentioned “addTwoSums” function.
Poor Documentation:
This example has clearly been written for functionality without consideration of explaining why or what it does, but hey it works right? :).
Good Documentation:
This example is good, as it shows appropriate commenting of the function you are looking at and its intended function.
Great Documentation (JSDoc):
This example is great, as it shows appropriate commenting of the function, its required parameters, and its intended function. It explains the types and extended intellisense capabilities throughout the codebase.
This is a simple example of JSDoc improving documentation standards for developers and can increase efficiency on enterprise level applications. JSDoc is native to IDEs such as Visual Studio Code, IntelliJ IDEA, and NetBeans. If you are currently not utilizing JSDoc for your javascript applications, it’s highly recommended to add to your arsenal for documentation. If you would like more information on this topic or would like to speak to one of our developers, don’t hesitate to reach out at connect@geo-jobe.com.
