Coding style & naming

Code that people can read

JavaScript does not care what you call a variable. A variable named x and a variable named minimumPrice work the same way. If the code follows JavaScript's rules, it runs.

People are different. We read the names, the spacing, and the comments to work out what a program does.

Coding style means the choices you make so that code is easy for people to read. It covers four things:

• the names you give to variables and functions,
• the layout: spaces, indents, and line breaks,
• the comments you write,
• whether you write each decision in a plain way or a tricky way.

Good style makes code easier to read, to fix, and to change later. This lesson uses only beginner JavaScript: const, let, functions, arrays, strings, numbers, true/false values, and a few if statements. The full rules for making variables come later, in the Variables lesson.

You already met comments and spaces in Statements, comments & semicolons, strict mode in Strict mode, and your editor in Setting up your tools. This lesson puts those basics together to make code easy to read.

A good name says what a value is for: the job it does in the program. price is better than n. If the price is the lowest price allowed, minimumPrice is even better. A name does not need to be long. It needs to say enough for someone reading the code around it.

JavaScript programmers usually write names in the styles below. Read each row as: for this kind of thing, write the name this way.

Function names usually start with a verb, an action word, because a function does a job: getUser, calculateTotal, renderMenu. Avoid short forms unless everyone on your team already uses them. Avoid numbers that mean nothing, like arr2. A reader should never have to guess.

const orderItems = ["tea", "notebook"];
const hasCoupon = true;

console.log(orderItems.length);
console.log(hasCoupon);

Line 1 makes an array, which is a list. The plural name orderItems tells you it holds more than one item. Line 2 stores true. The name hasCoupon reads like a question: does the order have a coupon? Line 4 prints 2 and line 5 prints true. The values are simple, and the names tell you what they mean before you look at them.

const cartTotal = 24;
const minimumFreeShippingTotal = 30;
const needsShippingFee = cartTotal < minimumFreeShippingTotal;

console.log(needsShippingFee);

Lines 1 and 2 name two numbers: the cart total, and the smallest total that ships for free. Line 3 compares them and stores the answer, true or false. Its name, needsShippingFee, says what that answer means. 24 is less than 30, so line 5 prints true. Later, if (needsShippingFee) reads almost like a sentence.

In the playground below, the function works, but its names are vague. Press a button to swap one vague name for a clear one.

1function doIt(arr2, x, flag) {2  let d = 0;3  for (const item of arr2) {4    if (item.price >= x) {5      d = d + item.price;6    }7  }8  if (flag) {9    d = d - 5;10  }11  return d;12}

The result did not change. That is what a safe rename means. The function still adds up the items that cost at least the minimum price, then takes 5 off when there is a coupon. The new version is just easier to read.

const userName = "Asha";
const MAX_RETRY_ATTEMPTS = 3;

console.log(userName);
console.log(MAX_RETRY_ATTEMPTS);

Both lines use const, so this program never gives either name a new value. Only the retry limit is written in capitals. It is a fixed rule for the whole app, like a setting. Line 4 prints Asha and line 5 prints 3. An ordinary value like userName stays in camelCase.

Formatting is the layout of code: indents, line breaks, spaces, quotes, semicolons, and commas at the end of lists. Messy layout can make working code look broken, because you cannot see which lines belong together.

Prettier is a popular formatter: a tool that rewrites the layout of your code for you. In a real project you install it, and your editor runs it. This page does not run Prettier. It shows a before-and-after pair that was written ahead of time. The "after" code is laid out the way Prettier lays it out with its default settings.

1const profile={name:"Mina",roles:["mentor","reviewer"]};2function greet(name){return "Hello, "+name+"!"}3console.log(greet(profile.name));

1const profile = {2  name: "Mina",3  roles: ["mentor", "reviewer"],4};5 6function greet(name) {7  return "Hello, " + name + "!";8}9 10console.log(greet(profile.name));

const user = { name: "Asha", badges: ["HTML", "JS"] };
console.log(user.name + " has " + user.badges.length + " badges");

Line 1 makes a small user object: one value with named parts, here a name and a list of badges. Line 2 reads the name, counts the badges, and prints Asha has 2 badges. The layout of this code could change. The program would still do the same work.

const price = 12;
const quantity = 2;
const total = price * quantity;

console.log(total);

This code is neatly laid out. It prints 24, because 12 times 2 is 24. Prettier can tidy the layout. It cannot tell you whether the quantity should be 2, or whether the price belongs to the right product. Tidy layout helps people spot mistakes. Tests, and other people reading the code, still check that the numbers are right.

In VS Code, many teams turn on Format on Save. Then the file is tidied each time you save it. A formatter is not the same as a linter. A formatter fixes layout. A linter, such as ESLint, reads your code and warns you about likely mistakes. Linters are the next lesson.

A comment is a note for people. JavaScript skips it. The best comments say something the code cannot say by itself, such as:

• the reason for a choice,
• a warning about something surprising,
• a short-term choice that must change later,
• how other files should use a function.

1// Adds 5 percent2const fee = subtotal * 0.05;3 4// Keep a small fee so tiny orders still cover card processing.5const minimumFee = Math.max(fee, 1);

The comment on line 1 repeats what line 2 already shows. The comment on line 4 explains why line 5 exists. Math.max gives back the biggest of the numbers you pass it, so the fee is never less than 1.

const orderTotal = 12;

// Keep a minimum fee so tiny card payments still cover processing.
const minimumFee = Math.max(orderTotal * 0.05, 1);
console.log(minimumFee);

Line 1 sets an order total of 12. Line 3 gives the reason for the smallest fee. Line 4 does the math: 5 percent of 12 is 0.6, and Math.max(0.6, 1) picks the bigger number, 1. Line 5 prints 1. The math shows what happens. The comment says why.

const orders = ["oldest", "newest"];

// Show newest orders first.
console.log(orders[0]);

A stale comment is out of date: the code changed, but the comment did not. Here, line 3 promises the newest order first, but line 4 prints oldest. When you see a mismatch like this, fix the code or fix the comment. Always change a comment in the same edit as the code it talks about.

The table lists the common kinds of comments. Read each row as: this kind of comment helps when…, and watch out for…

Clever code packs a lot of work into very few characters. It can feel smart to write, but it is slow to read. Here are some common tricks:

• a ternary inside another ternary. A ternary is the ? : operator: a one-line if/else, like paid ? "ship" : "wait".
• && used to run code, instead of to join two true/false checks,
• !!value to turn any value into true or false,
• ~~x to cut the decimal part off a number,
• long chains of one-letter names.

These tricks have uses in advanced code. But when a plain if says the same thing, the plain if is easier to read.

function canShowCheckout(hasItems, isOffline) {
  if (isOffline) {
    return false;
  }

  return hasItems;
}

console.log(canShowCheckout(true, true));
console.log(canShowCheckout(true, false));

The first call passes true, true: there are items, but the device is offline. The if on line 2 is true, so line 3 returns false and the function stops there. The second call is online, so it skips the if, reaches line 6, and returns true.

This pattern is called a guard clause: an early return for a case that cannot go on. Use one when it keeps the main path of the function short and flat.

Now compare a clever function with a clear one. Both are real functions, and the lesson's tests run both with many inputs. They always give the same message. The question is: which one would you rather change next month?

1function shippingMessageClever(itemCount, isMember) {2  return (3    (itemCount &&4      (isMember ? "Free shipping" : itemCount > 3 ? "Discount shipping" : "Standard shipping")) ||5    "Cart is empty"6  );7}8 9function shippingMessageClear(itemCount, isMember) {10  if (itemCount === 0) {11    return "Cart is empty";12  }13  if (isMember) {14    return "Free shipping";15  }16  if (itemCount > 3) {17    return "Discount shipping";18  }19  return "Standard shipping";20}21 22const itemCount = 4;Run23const isMember = false;24console.log(shippingMessageClever(itemCount, isMember));25console.log(shippingMessageClear(itemCount, isMember));

Where you’ll use this

Style matters anywhere someone reads code:

• your own notes while you fix a bug,
• a pull request: a request that asks your teammates to check your change and add it to the project,
• a tutorial or a team project,
• a file you have not opened for three weeks.

1const MAX_RETRY_ATTEMPTS = 3;2 3function canRetryRequest(errorCount, isOffline) {4  if (isOffline) {5    return false;6  }7  return errorCount < MAX_RETRY_ATTEMPTS;8}

• MAX_RETRY_ATTEMPTS is a fixed setting, so its name is in capitals.
• canRetryRequest starts with can, so you know it answers yes or no.
• isOffline reads naturally inside an if.
• The early return on line 5 handles the special case first, so the last line stays simple.

Apps make this kind of decision all the time. When a request to a server fails, the app can try again. Trying again is called a retry. A retry can help when the problem was short. It cannot help while the device is offline. So the function checks the offline case first, then checks the normal limit.

1function canRetryRequest(errorCount, isOffline) {2  if (isOffline) {3    return false;4  }5 6  return errorCount < 3;7}8 9const errorCount = 1;Run10const isOffline = false;11console.log(canRetryRequest(errorCount, isOffline));

With one failed try and the device online, the replay prints true. With three failed tries, it prints false. With the device offline, it also prints false, because the early return handles that case first.

const menuItems = ["tea", "coffee"];
const sortedMenuItems = [...menuItems].sort();

console.log(menuItems.join(", "));
console.log(sortedMenuItems.join(", "));

sort() puts an array in order, and it changes the array you call it on. So line 2 makes a copy first. In [...menuItems], the three dots are the spread syntax: they copy every item into a new array. Then sort() changes only the copy.

Line 4 prints tea, coffee: the original order. Line 5 prints coffee, tea: the sorted copy. The two names tell you which array is the original and which one is sorted. This habit stops you from changing a list that another part of the page still needs.

Before you share code, ask four questions:

• Do the names say what each value is for?
• Did the formatter run?
• Do the comments say why?
• Is any line so clever that a beginner would get stuck on it?

Common misconceptions

Try each task before you open the hints. The answer box checks an exact output or a short answer. The real skill is being able to say why you made your choice.

const arr2 = ["draft", "sent", "archived"];
const x = arr2.length;
console.log(x);

const statuses = ["draft", "sent", "archived"];
const statusCount = statuses.length;
console.log(statusCount);

const names = ["Ada", "Mina"];
const label = names.length ? names.join(" & ") : "Nobody";
console.log(label);

const names = ["Ada", "Mina"];
let label;
if (names.length === 0) {
  label = "Nobody";
} else {
  label = names.join(" & ");
}
console.log(label);

// Adds 7 because a week has 7 days
const reminderDay = signupDay + 7;

// Wait a full week so new users get one weekend before the reminder.
const reminderDay = signupDay + 7;

const user={name:"Ada",badges:["HTML","JS","CSS"]};
console.log(user.name + " has " + user.badges.length + " badges");

const user = {
  name: "Ada",
  badges: ["HTML", "JS", "CSS"],
};

console.log(user.name + " has " + user.badges.length + " badges");

const paid = true;
const inStock = false;
const message = paid ? (inStock ? "ship now" : "ship tomorrow") : "ask for payment";
console.log(message);

Your first try counts for the score. Every answer has an explanation. For code questions, follow the values step by step before you choose.

Key takeaways

• Name each value for its job: orderItems, minimumPrice, and hasCoupon are better than arr2, x, and flag.
• Follow the usual name styles: camelCase for variables and functions, PascalCase for classes, UPPER_SNAKE_CASE for fixed settings, is/has/can for true/false values, verbs for functions, and plural words for lists.
• Prettier is a formatter. It fixes layout, not logic. ESLint, in the next lesson, warns you about likely mistakes.
• Good comments say why, warn about surprises, or explain functions that other files use. Delete out-of-date comments and old code left in comments.
• Choose plain if statements over clever tricks, so the next reader can change the code safely.

Up next: Linting with ESLint.