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?
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.
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.
This example has clearly been written for functionality without consideration of explaining why or what it does, but hey it works right? :).
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.