Programming Concepts · Chapter 1 · Foundations

1.3 Documentation and Coding Conventions

How you name a variable — and whether you reuse it — decides whether your code explains itself later, or forces someone to guess.

bookSHelf  ·  Introduction to Programming Concepts and Methodologies  ·  §1.3  ·  a self-paced section

bookSHelf · Programming Concepts1 / 13
Titlepage: double rule over the sans title, one-sentence lede, hairline rule, small-print byline. Paper-white, link-blue accent, zero radius.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

Outline — by the end of this section you will be able to

Learning Objectives

  1. Choose clear, descriptive names for variables that communicate their purpose naming
  2. Explain why reusing variables for different purposes makes code harder to debug reuse
  3. Follow team naming conventions to keep code consistent and readable convention
bookSHelf · Programming Concepts2 / 13
Three objectives, one per click. The tag column names the habit each objective teaches.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.1 — the habit that separates beginner code from clear code

Naming Variables Well

A variable name should have a clean, obvious meaning — it should describe the data it stores. Looking at variable names can often tell you whether the code was written by a beginner or by someone with experience.

bookSHelf · Programming Concepts3 / 13
Topic intro: naming is one of the most important skills in programming.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

Context Pause — good naming communicates intent

Good naming communicates intent

Good naming is not about following rigid rules — it is about communicating intent. Code is read far more often than it is written, so spending a few extra seconds on a good name saves minutes of confusion later.

Unclear

let x = 29.99;

Clear

let totalPrice = 29.99;
bookSHelf · Programming Concepts4 / 13
Reading totalPrice tells you immediately what the variable holds; reading x forces a guess.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.1 — the naming rules, named

Definition 1.3.1: Variable Naming Rules

Definition 1.3.1 — Variable Naming Rules

Good variable names follow these guidelines:

  • Use human-readable names like userName, not a comment explaining a bad one.
  • Avoid abbreviations like a, b, c — a single letter tells the reader nothing.
  • Make names descriptive but concise — data and value say nothing about what they hold.
  • Agree on terms — if your team says “user,” name it currentUser, not currentVisitor.

Definition 1.3.1: use human-readable names, avoid bare abbreviations, keep names descriptive but concise, and agree on terms.

Reading a name should answer “what is this?” — without needing a comment to explain it.

bookSHelf · Programming Concepts5 / 13
The definition sits in a ruled paper box beside its def-figure. The clarifying line reveals on click as the takeaway.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.1 — Worked example

Example 1.3.1: Good vs. Bad Variable Names

Example 1.3.1 — Good vs. Bad Variable Names

Compare these two snippets. Both do the same thing, but one is much easier to understand.

let a = "John";
let b = 90;
let c = a + " scored " + b + "%";

Solution. Names that explain themselves:

let studentName = "John";
let examScore = 90;
let result = studentName + " scored " + examScore + "%";
bookSHelf · Programming Concepts6 / 13
Commit-first: the prompt shows, then one click reveals the descriptive-name solution below a hairline rule.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.1 — Practice

Try It Now 1.3.1

Try It Now 1.3.1

Look at these variable names. Which ones are good? Which ones are bad? Why?

let x = 5;
let numberOfStudents = 5;
let d = "Monday";
let currentDay = "Monday";
let temp = 98.6;
let bodyTemperature = 98.6;

Answer: x, d — bad, no information. numberOfStudents, currentDay, bodyTemperature — good, descriptive. temp — borderline; bodyTemperature says it more clearly.

bookSHelf · Programming Concepts7 / 13
Students should judge each name before clicking to reveal the answer.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.2 — the second habit: don’t relabel the box

Reuse or Create?

Some programmers save a bit of typing by reusing the same variable for different purposes, instead of declaring a new one. Imagine a box labeled “books” that you keep using to store shoes, then dishes, then toys, without changing the label — after a while, nobody knows what is actually inside.

bookSHelf · Programming Concepts8 / 13
Topic intro: reusing a variable is a bad habit that hides what it currently holds.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.2 — the same three values, two variable strategies

Reuse vs. Create

Reused (bad)

let item = 42;
console.log(item);
item = "hello";
console.log(item);
item = true;
console.log(item);

Separate (good)

let answer = 42;
console.log(answer);
let greeting = "hello";
console.log(greeting);
let isComplete = true;
console.log(isComplete);

By the third line, item could be anything. answer, greeting, and isComplete each stay exactly one thing.

bookSHelf · Programming Concepts9 / 13
Same three values, two strategies. The footnote names the cost of reuse: you lose track of what the variable means.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

Insight Note — reuse costs debugging time, not typing time

Extra variables don’t slow your code down

Modern JavaScript engines optimize variables away, so extra ones cost nothing at runtime. The real cost of reuse is that you must track what a variable holds at every point in the program — one wrong assumption becomes a bug that is hard to find.

bookSHelf · Programming Concepts10 / 13
Confusing variables slow you down, not extra ones.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3.2 — Practice

Try It Now 1.3.2

Try It Now 1.3.2

The following code reuses a variable. What is confusing about it? Rewrite it using separate variables with clear names.

let x = 100;
console.log(x);
x = "Alice";
console.log(x);
x = true;
console.log(x);

Answer: x holds a number, then a string, then a boolean — by the third line you can’t tell what it represents. Rewrite with maxScore, playerName, isGameOver.

bookSHelf · Programming Concepts11 / 13
Same reuse problem as the definition example, now with clear replacement names.
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

Glossary — terms introduced in this section

Key Terms

Coding convention

A set of guidelines for writing code that is consistent and readable.

Descriptive name

A variable name that clearly communicates what the variable holds.

Variable reuse

The practice of using the same variable for different purposes, which makes code harder to understand and debug.

bookSHelf · Programming Concepts12 / 13
Key terms glossary: all three terms from the section's Key Terms table.
1.3
1.3 Documentation and Coding Conventions · bookSHelf Programming Concepts§1.3

§1.3 — Conclusions

What to carry forward

The one idea

Name variables so they describe what they hold — human-readable, not abbreviated, descriptive but concise, and matched to your team’s own vocabulary.

The common mistake

Reusing one variable for different kinds of values hides what it means at any given point — the code still runs, but nobody, including future you, can tell what it holds.

Next: §1.4 Programming Paradigms and Languages. Back to start.

bookSHelf · Programming Concepts13 / 13
Closing argument in two ruled cards — the core idea under a heavy top rule, the common mistake beside it — over a ghost section numeral. The next-step line reveals last.