ProgramGuru

Write Code People Can Read

Help the next teacher understand the calculation

A school report works, but the next person sees variables a, b and c and cannot tell whether they represent marks, fees or attendance. Correct output alone does not explain the intention.

Readable code helps a person understand what the program does and why its choices make sense. Clear names, consistent layout and focused operations make it easier to check and change a program safely.

  1. Name the intention

    Choose names that explain the school data and calculation.

  2. Explain a rule

    Write a useful reason or constraint in a comment.

  3. Review a change

    Compare readability without changing the result.

Make the calculation understandable at each stage

  1. Named data

    Explain what each value represents.

    mathsMark, scienceMark

  2. Focused operation

    Name the calculation rather than its implementation.

    calculateAverage

  3. Clear result

    Use the result in a report.

    average: 37.5
Read these stages alongside the complete example. They explain the relationship; they do not execute code.

Readability is about understanding, not maximum verbosity

A name should reveal a relevant meaning in its context. mathsMark is useful here; a vague a loses context, while currentStudentSchoolMathsSubjectNumericMark repeats information that nearby code already supplies.

Consistent indentation shows which statements belong together. Small functions can give a rule a name, but splitting every arithmetic operator into its own function can make the whole task harder to follow.

Before starting, review focused functions. These examples use JavaScript; other languages can use different syntax and rules.

Give the report calculation a clear purpose

The parameter names identify the two inputs and the function name identifies the result. The comment explains a school policy: both subjects have equal weight. It does not merely repeat that division occurs.

The function calculates one value; the caller decides to display it. This makes the calculation easier to reuse and test.

JavaScript · local teaching example

function calculateAverage(mathsMark, scienceMark) {
  // School policy: both subjects have equal weight.
  return (mathsMark + scienceMark) / 2;
}
console.log(calculateAverage(40, 35));

Expected output

37.5

Compare equivalent code with weaker names

This calculation produces the same number but makes readers recover the meaning from elsewhere. Readability changes should preserve behavior unless a separate behavior change is intended.

For a tiny demonstration, short names may be understandable. In a shared report project, subject names make the inputs easier to check.

JavaScript · local teaching example

const a = 40;
const b = 35;
const c = (a + b) / 2;
console.log(c);

Expected output

37.5

Apply the rule to a small change

Calculate whether a student with mark 25 passes, using a named threshold and a clear boolean variable.

Worked answer

A named passMark explains why 25 matters. The >= operator includes the boundary mark, and hasPassed explains what the boolean means.

JavaScript · local teaching example

const mark = 25;
const passMark = 25;
const hasPassed = mark >= passMark;
console.log(hasPassed);

Expected output

true

Recognize mistakes and limits

A comment can become inaccurate when code changes. Keep policy comments close to the rule and update both together. Prefer code that expresses the operation clearly over comments repeating each instruction.

Avoid unexplained numbers when they represent changeable rules. Not every zero or one needs a named constant; name values when that name adds meaning.

Use the project’s established conventions rather than introducing a new style in each file. Review names, control flow and error handling from the perspective of someone unfamiliar with your change.

For the language or tool rules used here, see JavaScript function interfaces.

Check the core idea

Which comment adds useful information to this average calculation?
Choose one answer. You can try again.

Answer and explanation

School policy: both subjects have equal weight.

Correct. It explains why this calculation is the appropriate rule.

Apply the idea to a new situation

A naming-only refactor should usually do what to output?
Choose one answer. You can try again.

Answer and explanation

Preserve the calculation’s behavior.

Correct. Clearer expression should still implement the same agreed rule.

Write for the person who checks and changes the rule

Useful names, focused operations and reason-based comments make behavior easier to assess. Preserve results while improving expression, and keep explanations synchronized with code.

Connect this idea with one authoritative shared rule and checking behavior during changes.

Reaching the recap and completing the quizzes are separate milestones.

    Next lesson: Reuse a Shared Rule →