1.3 Documentation and Coding Conventions

Step 1 — Reading the code: let a = 5; creates a variable named a and stores the number 5 in it. The code works fine — JavaScript doesn't care what you name a variable.

Step 2 — Why the name is poor: The name a tells you nothing about what the value 5 means. Is it a score? A price? A temperature? A person's age? When you (or a teammate) read this line later, you have to hunt through the rest of the code to figure out what a is for. A good variable name should describe the value it holds.

Answer: a is a poor name because it gives no information about what the value means. A better name describes the value, for example let score = 5; or let age = 5; — whatever the 5 actually represents.

Step 1 — What "reusing a variable" means: Reusing a variable means storing one kind of value in it, then later storing a different kind of value in the same variable — for example, first a number, then a string, then a boolean.

Step 2 — Why it causes problems: When you read code that reuses a variable, you can never be sure what kind of value it holds at any given moment. That makes the code confusing and easy to break: a line that expects a number might get a string, and the program produces a wrong result or crashes. It also hides the program's meaning — a variable that holds "a name" and then "a price" doesn't represent either one clearly.

Answer: Reusing a variable for different kinds of values is a problem because it makes code confusing and error-prone — readers can't tell what the variable holds, and operations that expect one kind of value may silently get another. Each variable should hold one kind of value, with a name that says what it is.

Step 1 — What the two names say: currentMember says the variable holds the person currently logged in, described as a member. currentPerson says the same thing, but described as a person.

Step 2 — Matching the team's vocabulary: Your team calls a logged-in person a "member" — that's the word everyone on the team already uses when talking about the code. When a variable name matches the team's own language, anyone reading the code instantly connects it to the concept they already know. currentPerson is not wrong, but it introduces a second word for the same idea, which can cause confusion.

Answer: currentMember is better, because it matches the team's vocabulary — the team calls a logged-in person a "member," so the variable name should use that same word. Names that match the language of the people working on the code are the clearest.

Step 1 — Figuring out what each variable holds:

• a holds the name of a subject: "Math".
• b holds a numeric grade: 88.
• c holds a sentence built from the other two: "Math final grade: 88%".

Step 2 — Choosing descriptive names and rewriting: Give each variable a name that says what it holds — subject, grade, and message (or finalGrade). The code does exactly the same thing, but now a reader understands it at a glance:

▶ Press Run to see the output…

The behavior is identical, but the meaning is now clear.

Step 1 — What the claim says: The claim is that every extra variable you create makes your program run slower, so you should use as few variables as possible.

Step 2 — What actually happens: Modern JavaScript engines are very good at optimizing. They figure out what a variable is used for and often remove or reuse it internally — so an extra variable usually costs nothing at runtime. In fact, extra variables can make a program faster to develop and maintain, because clear names help you (and others) understand and fix the code more quickly. The real cost of a variable is not speed — it's clarity, and clear code is worth the tiny cost.

Answer: False. Extra variables do not meaningfully slow down your program — modern engines optimize them away. They can even help, because well-named variables make code easier to read, understand, and fix, which saves far more time than a few extra variables could ever cost.

Step 1 — Understand the guideline: "Descriptive and concise" means a name should tell you what the value is (descriptive) without being long or wordy (concise). A good name like userName reads like a sentence: "this is a user's name." A bad name either says nothing (x, abc) or is so generic it could mean anything (data, num).

Step 2 — Check each name against the guideline:

• userName — follows the guideline. It clearly holds a user's name, and it's short.
• totalPrice — follows the guideline. It clearly holds the total price, and it's short.
• x — does not. It is a single letter with no meaning.
• data — does not. "Data" could be anything — a list, a number, a string. It is too generic.
• num — does not. It is an abbreviation that does not say what number it holds.
• abc — does not. It is a meaningless string of letters.

Answer: userName and totalPrice follow the "descriptive and concise" guideline. x is too vague, data is too generic, num is an abbreviation with no context, and abc is meaningless.

Step 1 — Figure out what each variable actually holds: Read the code and ask: what real-world thing is each value? n is set to 3 — a count of items, so it is a quantity. d is set to 2.5 — a price per item, so it is a price per item (or unit price). p is the result of multiplying them — the total price.

Step 2 — Rewrite with descriptive names: Replace each vague name with a name that says what the value is:

▶ Press Run to see the output…

Now the last line reads like a sentence: "total price equals quantity times price per item." Anyone can understand the code without guessing.

Answer: The rewritten code uses quantity, pricePerItem, and totalPrice — each name describes exactly what the variable holds, so the code explains itself.

Step 1 — Identify the problem: Your team has agreed to call a shopping cart a "basket," but your teammate's code uses cartItems while your new code uses basketItems. Both names refer to the same thing — the same concept, the same data. This is an inconsistent naming problem: two names for one concept. Anyone reading the code will wonder whether cartItems and basketItems are different things, and future changes (like renaming one) become risky and confusing.

Step 2 — Decide what to do: The team's word is "basket," so the team convention wins: the code should use basketItems. You should talk to your teammate, agree on the single name, and update the teammate's code to use basketItems everywhere. The goal is one concept, one name, used consistently across the whole codebase.

Answer: The problem is inconsistent naming — the same concept is called cartItems in one place and basketItems in another. The fix is to agree on the team's name (basketItems, since the team says "basket") and update the teammate's code to match, so the whole team uses one name for one concept.

Step 1 — Review each name and its weakness:

• x — a single letter. It gives you no hint at all about what the value is. That is too generic.
• temp — short for "temporary." It is an abbreviation, and on its own it gives no context about what is being stored (a temperature? a temporary value?). That is an abbreviation with no context.
• a1 — a letter plus a number. It says nothing about the value; it is just a label. That is a numbered name that says nothing.
• myVariable — it sounds fine and harmless, but "my" and "variable" carry no information about the value. That is meaningless but harmless-sounding.

Step 2 — Fill in the blanks: Match each name to its problem:

• Too generic: x
• Abbreviation with no context: temp
• Numbered name that says nothing: a1
• Meaningless but harmless-sounding: myVariable

Answer: Too generic: x — Abbreviation with no context: temp — Numbered name that says nothing: a1 — Meaningless but harmless-sounding: myVariable. All four fail the "descriptive and concise" guideline, just in different ways.

Step 1 — Write the first snippet with poor names: Store a student's name, score, and whether they passed using vague one-letter names:

▶ Press Run to see the output…

This works, but it is hard to read. What is n? What is s? What does p mean? A reader has to guess — or worse, a reader might guess wrong.

Step 2 — Write the second snippet with clear names, then compare: Store the same data with descriptive names:

▶ Press Run to see the output…

Now compare the two. In the second snippet, each line explains itself: studentName holds a name, score holds a score, and passed clearly holds whether the student passed. The line passed = score >= 60 reads like a sentence: "passed is true when the score is at least 60." The first snippet forces the reader to memorize what n, s, and p stand for; the second snippet needs no memorization at all.

Answer: The second snippet is far easier to read because studentName, score, and passed describe their values, while n, s, and p hide them. Good names let the code explain itself — that is why the "descriptive and concise" guideline matters.