Improve your JavaScript with documentation magic 📖 💫
In the last post I talked about why we should be modularising our JavaScript:
In this post we’ll be really getting our hands dirty!
Why we should document 📝
When we write modular JavaScript and we start moving functions into separate files, you’ll probably have a harder time using those functions without going to look at them. With some documentation magic we can easily know:
- what a function does
- which parameters it can accept
- what the function returns
And believe me, whenever you have code that is more than 3 months old, you will always have to re-read it to understand it. This can be much much easier if you have your own inline documentation!
Also, since in this series we will be working towards writing our first NPM module, documentation is a kind gesture to anyone you might be sharing your code with. 😊
Our example function
Let’s look at an example function that works best when modularised.
Eg. we have an app that uses large numbers with many decimals, and we need to only show the number rounded up or down with maximum x decimals. As per example we want the number 0.12345 to become 0.123.
A simple integration could be:
Now we can do roundDecimals(0.12345, 3) and get back 0.123.
Exporting and importing
This is easy, and I’m sure anyone reading this probably already knows how to do this. 😉
(but a quick review) By just saving your function inside a separate file called eg. roundDecimals.js like so:
This makes it possible to, in any other file, import and use this function like so:
However, the main problem is, the more we modularise our code, the more files we have… This often makes it annoying to go look in those other files what exactly the function was, which parameters it receives etc. Let’s solve this with some documentation magic!
Text editor default functionality
Most text editors have pretty good out-of-the-box functionality for documentation. I’m going to give a short example for VSCode what happens when you hover over roundDecimals() from our example above:
And when holding command (on macOS) it gets even better:
We can then even click on the function name to go to that file.
However, where this default documentation lacks is that we do not have any explanation for what the function does, returns or accepts as params. 😕
Ok sure, we can see the whole function when holding command, but this quickly gets unhandy when your functions are longer.
Add your documentation magic 🧙♂️ 💫
To get better feedback on what the function does, returns and accepts as params, we need to add our own documentation.
I will show how easy it is to add that information with the JSDoc-standard. First you should search a plugin for your text editor called ‘document this’. With this plugin you can right click on any function and choose “document this”. That gives you a nicely formatted documentation block that looks like this:
Now we can just fill in the information regarding what the function does, returns and accepts as params. See the example below:
After adding this information, look how our function feedback in VSCode has completely changed:
This might differ slightly depending on which text editor you are using, but most modern ones are pretty good with passing around function documentation!
Phew! That was easier than you expected huh! Trust me, a little documentation effort goes a long way!
Live long and prosper 🎉
Yours truly,
- Luca Ban (github)
