JavaScript Best Practices — Comments and Spaces
By: John Au-Yeung
Tags: Programming, JavaScript, Software Development, Web Development, Technology

Photo by Demi-Felicia Vares on Unsplash

JavaScript is an easy to learn programming language. It’s easy to write programs that run and does something. However, it’s hard to account for all the uses cases and write robust JavaScript code.

In this article, we’ll look at the best ways to work with comments and spaces.

Comments

We should be careful when writing JavaScript. We want them to be readable like anything else.

Use /** ... */ for Multiline Comments

The /** ... */ block denotes that a multiline comment inside it.

It’s better than // since we can write our comments in one block.

For example, instead of writing:

// foo

// bar

We can write:

/**

* foo

* bar

*/

Use // for Single Line Comments

// is great for single-line comments. We should put a single line above the subject of the comment.

And an empty line should be added before the comment.

For instance, we should write:

function getType() {

// returns type

}

or:

function getType() {

console.log('get type'); // returns type

}

Prefix FIXME and TODO to Label Code that Needs Changing Later

We can change FIXME and TODO to label code that needs changing later.

This way, we won’t forget about them.

We just have to remember to remove comments after we’re done.

For instance, we can write:

// TODO - clean up code

If our code has Problems, then use // FIXME to Mark Them

For instance, we can write:

// FIXME - remove global variable

so that we can fix that.

Use // TODO to Mark Solutions to a Problem

If we have a solution that we don’t have time to implement yet but we have an idea of how to do it, we should use // TODO to mark that.

For instance, we can write:

// TODO - make total configurable

to mark the solution to some problem that hasn’t been implemented yet.

Whitespace

Spaces make things easier to read, so we should add them consistently.

Use Soft Tabs Set to 2 Spaces

Spaces are consistent among operating systems, so they’re better than tabs.

2 spaces make things readable without too much typing.

So instead of writing:

function foo (){

let x;

}

We write:

function foo (){

let x;

}

We can also configure our text editor to convert 1 tab to 2 spaces automatically to save typing.

Place 1 Space Before Leading Brace

We should place 1 space before a leading brace so that we can read our functions easier.

For instance, instead of writing:

function foo(){

console.log('foo');

}

We write:

function foo() {

console.log('foo');

}

Likewise, with arrow functions, instead of writing:

const foo = () =>{

console.log('foo');

}

We write:

const foo = () => {

console.log('foo');

}

With function calls, instead of writing:

person.set('attrs',{

age: 1,

gender: 'male'

});

We write:

person.set('attrs', {

age: 1,

gender: 'male'

});

Just one space makes things more readable.

Place 1 Space Before the Opening Parenthesis in Control Statements

If we’re writing conditional statements or loops, we should have 1 space before the opening parenthesis.

And we should have no pace between the argument list and the function names in function calls and declarations.

For instance, instead of writing:

if(foo) {

bar ();

}

We should write:

if (foo) {

bar();

}

Likewise, for loops, instead of writing:

while(foo) {

bar();

}

We write:

while (foo) {

bar();

}

For function definitions, instead of writing:

function foo () {

console.log ('bar');

}

We write:

function foo() {

console.log('bar');

}

The spacing makes our blocks more readable.

Photo by Clayton Cardinalli on Unsplash

Set Off Operators with Spaces

We should have spaces between operands and operators to improve readability.

For instance, instead of writing:

const x=y+1;

We write:

const x = y + 1;

End File with a Single New Line Character

We should always end a file with a single newline character.

This way, they can always be concatenated properly by programs that do that if needed.

For instance, instead of writing:

index.js

const x = 1;

We write:

index.js

const x = 1;



Conclusion

Spacing is important. Therefore, we should have them in places where they make sense.

If we write comments, we should denote multiline comments in a different way than single-line comments.

We may also use comments to denote todo items and things that need fixing.

Newline character should be at the end of file so that it can be concatenated properly with other files.