Always Comment Your Function..!!

Let’s dig in about the reason why we need to write the documentation as code in our repository.

A featured image

Commenting on something is basically a way for someone to judge or give a different perspective of something, whether it’s in terms of good or bad in the process, we will consider whether we will improve based on it or just ignore it, according to the comments that given to us.

But, in this post, we will not talk about politics, but it’s more technical on Web Development, and my perspective is why we need to do this during we write our code.

In our discussion this time, we will see how important it is to comment on a function that we have created ourselves, of course in JavaScript. Imagine we have a function like this:

function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Basically, how do we read a function in JS just directly what function name has been provided, in our case above we named it as `setLocation` we will conclude that function will set a new location, but what kind of location? what is the purpose? below we will try to understand bit-by-bit to know better that function.

window.location.href = `${x}://${y}`;

Oh, turns out that function will execute a location of the URL at the address bar browser or something like that, with a note we should fill in some arguments `x` and `y`.

What's The explanation of arguments `x` and `y`? whether we will fill in `object` or `string` or maybe we can fill in some special input? another we use Typescript, the type data mechanism will be done by Typescript itself on runtime or maybe on development, but how about we use JavaScript?

Yes, in JavaScript (JS) the arguments in the `setLocation` the function will be displayed by the IntelliSense editor as `any` meaning whatever the data is will be allowed.

As you can see basically, there is two’s problem here; Computer and a Human, when the computer reads the code will continue to run no matter the argument name we have set, but what about a Human?

The function we create will be difficult for the next developer (Human) to understand, because without knowing what to send to the `setLocation` function, it's different if we leave a comment

// args `x` with data type string, is a protocol
// args `y` with data type string, is a domain name
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

We will understand the code and we will use it according to the comments given, this is better than before, at least we understand what to send into the function we create.

We will try to comment on the function we created, according to the standard of JSDoc, we will change the above comment to something like this

/**
 * A function that can be executed on address bar browser
 * @param {string} x a host url
 * @param {string} y a domain url
 */
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

In the above function, we have modified the comments according to the JSDoc directive provided, this will be more aesthetic, and also IntelliSense in the editor will appear like using TypeScript.

Indeed, IntelliSense it’s just can help users to determine what should be sent in that function when we want to use that, but it’s not totally typed strict

This is very helpful especially if we have a function where we should send a data object as a parameter of the function, for example, we have a function like this

/**
 * @param {object} fullName
 * @param {string} fullName.firstName your first name
 * @param {string} fullName.lastName your last name
 */
function overwriteData(fullName) {
  return {
    firstName: "Adib",
    lastName: "Firman",
    ...fullName
  };
}

When we want to use the `overwriteData` function it will ask for a parameter with the contents of an object, instead of opening the original source of the function to find out what the object is, we have put a comment on the function, when we want to use it

Alike usual IntelliSense will give us a hint, and you know that the more interesting for this approach is

In the picture above we will enter data according to the instructions from IntelliSense of course we will get a hint from our editor, interesting, isn’t it?

The next question is, should we comment on all the functions that we have created? Of course not, an example of a function like this

const sum = (firstNum, secondNum) => firstNum + secondNum;

When we want to use the function, we already know from the given argument name, and from the function name it is `sum` which only adds up to two values.

Conclusion

Put some comments on our function, depending on how it will be used are the given parameters very complex? or is it readable from the naming function and arguments created?

But if you feel that the function needs to be given a comment, that’s better, because it is to make it easier to maintain by the next developer (Human).

Thank you.