Comments
There are two types of comments in JavaScript:
- Inline comments (
//...
) - inline to statements, expressions, etc - Multi-line comments (
/*...*/
) - span multiple lines;
Comments are notes describing how and why the code works. It is crucial as a reminder to the creator of the code and when working with other developers.
If the code has anything subtle and counter-intuitive, it's definitely worth commenting.
There are times when novices use them wrongly.
Bad Comments
Many comments are bad practices. The example shows the logic of creating a prime number in JavaScript in bad comments.
See the example below:
function showPrimes(n) {
// nextPrime is just a label
nextPrime:
for (let i = 2; i < n; i++) {
/*
The iteration starts at 2 through to n - 1. For example, if n is
10, iteration starts from iteration 2 to iteration 9. 9 is
less than 10
*/
for (let j = 2; j < i; j++) {
// iteration from j = 2 to j < i in all j complete circles
if (i % j === 0) continue nextPrime;
/* if iteration of i and j modulus equals zero then it's not
a prime number */
}
console.log(i); // 2, 3, ...7
}
}
showPrimes(10)
Good Comments
Comments should be logical (when necessary) but short.
See the example below:
const showPrimes = (n) => {
nextPrime:
for (let i = 2; i < n; i++) {
// 2, 3, 4, 5, 6, 7, 8, 9
for (let j = 2; j < i; j++) {
// j2 = 2,
// j3 = (2, 3),
// j4 = (2, 3, 4),
// j5 = (2, 3, 4, 5),
// j6 = (2, 3, 4, 5 ,6),
// j7 = (2, 3, 4, 5 ,6, 7),
// j8 = (2, 3, 4, 5, 6, 7, 8)
// i2
// i3 : j2
// i4 : j2, j3
// i5 : j2, j3, j4
// i6 : j2, j3, j4, j5
// i7 : j2, j3, j4, j5, j6
// i8 : j2, j3, j4, j5, j6, j7
// i9 : j2, j3, j4, j5, j6, j7, j8
if (i % j === 0) continue nextPrime;
// i2 => 2,
// i3 : j2 => (3 / 2) (3),
// i5 : j2, j3, j4 => ( 5 / (2, 3, 4) ) (5),
// i7 : j2, j3, j4, j5, j6 => ( 7 / (2, 3, 4, 5, 6) ) (7)
}
console.log(i); // 2, 3, 5, 7
}
};
showPrimes(10);
The comment above looks logical but overused.
See the example below of reduced comments:
function showPrimes(n) {
nextPrime:
for (let i = 2; i < n; i++) {
// i = i2, ...i(n-1)
for (let j = 2; j < i; j++) {
// in = j1, ...j(n-2)
if (i % j === 0) continue nextPrime;
// !R(i/j)
}
console.log(i);
}
}
showPrimes(10);
Not only the comment above is short, but also precise.
Good comments contain the following:
- Describe the architecture
- Document function parameters and usage
/**
* Returns x raised to the n-th power.
*
* @param {number} x The number to raise.
* @param {number} n The power, must be a natural number.
* @return {number} x raised to the n-th power.
*/
function pow(x, n) {
// ...
}
such comments above make the function understandable without looking in its code
some editors like WebStorm understand comments to provide autocomplete and some automatic code-checking to ease workflow
tools like JSDoc 3 that can generate HTML-documentation from the comments. The official documentation is at usejsdoc.org/
Most of the time comments are used in development only but removed in production especially when minified.
Code refactor
Code refactoring is the process of modifying the code structure without affecting the functionality for readability purposes.
See the example below:
function showPrimes(n) {
nextPrime:
for (let i = 2; i < n; i++) {
for (let j = 2; j < i; j++) {
if (i % j === 0) continue nextPrime;
}
console.log(i);
}
}
showPrimes(10);
To refactor or make the code more readable above see the example below:
function showPrimes(n) {
for (let i = 2; i < n; i++) {
if (!isPrime(i)) continue;
console.log(i);
}
}
function isPrime(n) {
for (let i = 2; i < n; i++) {
if (n % i == 0) return false;
}
return true;
}
showPrimes(10);
The code above looks easier to understand because it has lesser nesting and better factored out function isPrime
.
The function itself becomes the comment. Such code is called self-descriptive.
Refactoring split code structure to make functions more understand.
Happy coding!
TechStack Media | Domain
- Purchase a
.com
domain name as low as $9.99. - Purchase a
.net
domain name as low as $12.99. - Get cheaper domain names as low as $3.
- Build a website with ease.