As the BAR hosts many projects that turnover from student-to-student it is incredibly important not to only have a standardized application (the starter app I introduced), but also to document your code correctly. Today I will introduce JSDoc 3, the current de-facto standard for documenting your JS code. Fortunately, the format for JSDoc is similar to other documentation standards such as Python Docstrings. Some first steps that preclude documenting your code (as JSDoc doesn’t mandate naming conventions) is to use clear, explicit, and legible function, variable and file names. Also if your project is large and uses a framework such as a React, consider using multiple folders to contain your smart versus dummy components in a specific folder. The above principles apply compartmentalization and self-documenting code. However, self-documenting code is arguably an oxymoron, especially in your applications, as another student will have to parse through it.
In general you want to always being creating functions, as JS considers functions as first class citizens (remember callbacks?). Therefore you should always be documenting your functions.
However, JSDoc also has rules to document:
- files (basically a header)
- classes
- modules
- much more!
The standard format to document a function with JSDoc:
/**
* Multiply two numbers together
* @param {number} num1 - The first number to be multipled
* @param {number} num2 - The second number to be multipled
* @return {number} The product of the two numbers
*/
const addTwoNumbers = function (num1, num2) {
return num1 * num2;
};Some other options such as optional params, multiple variable types, or array params:
/**
* Concantate two arrays together. Optionally, if a second array is not given, append a dummy array.
* @param {Array} array1 - The first array of items to be concantated
* @param {Array} [array2="[1,2,3]"] - The second array to be appended to the first
* @return {Array} - resultant concantated array
*/
const concatArrs = function (array1, array2=[1,2,3]) {
return array1.concat(array2);
};For more complicated functions, you should also include inline comments to explain what is also happening:
/**
* Add two numbers together, type coercion if necessary.
* @param {string|number} num1 - The first num
* @param {string|number} num2 - The second num to be added
* @return {number} - resultant sum
*/
const concatArrs = function (num1, num2) {
// parseFloat coerces type to floating number
return parseFloat(num1) + parseFloat(num2);
};Also note you can be more specific in your type tags. For example, if you create a class, you can denote an array of instances of that class instead of generic objects.
/**
* Lorem epsum.
* @param {MyClass[]} arrayOfClasses - Array of my custom class instances
* @return {number} - Lorem epsum
*/The final test to see if your comments follow JSDoc standards is to run the JSDoc documentation generator on your JS file. Install JSDoc globally on your computer via npm install -g jsdoc and then run jsdoc yourJavaScriptFile.js . You’ll get a HTML file you can then open in your browser. See github for more details.
Alternatively, I recommend trying out installing the JSDoc eslint plugin to your package to actively scan for the correct syntax.
Task: Document one of your more complicated functions (from your application). Verify it follows JSDoc standards (run the commands above). Then see if your fellow students understand what the function does. Refactor your comments if it doesn’t! Remember, you’re commenting to other people (and future yourself), not to a JSDoc compiler!