Clean Code

Writing Clean Code

Developers spend SO MUCH more time reading code than writing it. This is true even with your own code. As a favor to yourself and whoever will need to use, maintain, or further develop your code, please learn to write readable code.

Consider the following 2 snippets of JavaScript:
ugly, hard to read code:

const x =
function(z) {
let w = 0;z.forEach(
function(q){
     w += q;
});return w;
};
x([2, 2, 2]);

clean and easy to read code:

const sumArray = function(array) {
  let sum = 0;
  array.forEach(function(number) {
    sum += number;
  });
  return sum;
};
sumArray([2, 2, 2]);

Believe it or not, both of those functions do the exact same thing (in the exact same way!), and both of them are perfectly valid code, but obviously the second one is much easier to follow. Imagine you’re working on a project with someone else and they’ve written the first function… how long is it going to take you to figure out what’s going on there so you can do your work? Imagine you’re working on a project all by yourself and YOU wrote the first function a week or two ago… chances are good that you aren’t going to remember exactly what you were up to there and it’s still going to take you a good while to figure it all out again.

The second one, however, is much easier to follow. Even if you don’t know exactly what everything in the code is doing, things are named clearly enough that you could guess, and the indentation is consistent enough that it’s easy to parse the different parts of the function.

There are many different opinions on what constitutes great JavaScript code. The most important thing is just that you’re consistent. The war between coders that use tabs and coders that use spaces to indent their code is so engrained that it’s essentially a joke by now, but it doesn’t really matter as long as you’re consistent.

Rules of Thumb

  1. Indentation: It doesn’t really matter what style of indentation you use. Various JS style-guides recommend different options, and one is not really superior to the other. What is important, however, is consistency. In our examples we will use 2 spaces for indentation.

  2. Semicolons: Semicolons are mostly optional in JavaScript because the JS compiler will automatically insert them if they are omitted. This functionality CAN break in certain situations leading to bugs in your code so…

It is better to get used to adding semi-colons;

  1. Line length: Again, different style guides will recommend different options for this one, but just about ALL of them suggest limiting the length of each line of code. This rule is not quite as strict as some of the others, but as a general rule, your code will be easier to read if you manually break lines that are longer than about 80 characters. Many code editors have a line in the display to show when you have crossed this threshold. When manually breaking lines, you should indent the second line 2 levels, and should try to break immediately after an operator or comma:
   let reallyReallyLongLine = something + somethingElse + anotherThing +
   		howManyTacos + oneMoreReallyLongThing;
  1. Naming Things: Names for functions and variables should be descriptive. Always use camelCase. To keep things consistent and easy to read, variables should always begin with a noun and functions with a verb. It is ok to use single characters as variable names in the context of a loop or a callback function, but not elsewhere.
   // Good
   const numberOfThings = 10
   const myName = "Thor"
   const selected = true
   // Bad (these start with verbs, could be confused for functions)
   const getCount = 10
   const isSelected = true
   // Good
   function getCount() {
     return numberOfThings
   }
   // Bad (it's a noun)
   function myName() {
     return "Thor"
   }

Study

Read through these articles that discuss a few elements of writing good clean code.

  1. This list of clean-code tips.

  2. This article, and this one too about the role of comments in your code.

  3. Study the following examples (all of them are real examples from student code) and make use to keep these rules in mind when naming variables yourselves:

Proper Naming for Functions and Variables

  • Name your variables and functions according to what they do.
  • Use verbs for functions and nouns for variables
  • Try to use descriptive names.
Example 1

BAD

myFunction(){ ... }
myFunction2(){ ... }

BETTER

function openMenu(){ ... }
function closeWindow(){ ... }
Example 2

BAD

This next function displays a range input field.

function rangeOutput(){ ... }

BETTER

It should probably be named using a verb that describes what it does.

function outputRange(){ ... }
Example 3

BAD

Can you guess what does the next function do? The name is too vague and ambiguous.

propTypeFunction();
Example 4

BAD

let sortArray = [ 1, 3, 2 ];
sortArray.sort();

BETTER

Prefer nouns when naming variables.

let sortedArray = [ 1, 3, 2 ];
sortedArray.sort();
Example 5

BAD

What does the tempArray hold? Try to be more descriptive.

let tempArray = entries.filter( getOdd );

BETTER

let oddEntriesArray = entries.filter( getOdd );
Example 6

BAD

What kind of object does the variable hold?

let object = new Category( categoryId, $categoryName );
// OR:
let object = new Article( articleId,  text);

BETTER

let category = new Category( categoryId, categoryName );
let article = new Article( articleId, text );

Assignment

Your instructor will share a link to the assignment repository. Work on your assignment and submit your Pull Request link in the Quiz below.

Additional Resources

Back to Lesson