Refactoring: changing the shape without changing the answer

Refactoring is changing the shape of code that already works, while its behaviour stays exactly the same. Same inputs, same outputs, same errors, same everything an outsider could observe. Only the arrangement changes: where things live, what they are called, which parts have been given names.

That definition is strict on purpose, because the word gets used loosely for 'rewriting while also adding things', and those two activities have opposite risk profiles. When behaviour is fixed, your checks are a safety net: they were green before, they must be green after, and any red one is a mistake you just made. Change behaviour at the same time and the net is gone - a failing check might be the new behaviour or might be a bug, and you cannot tell which.

So the rule is: refactor, run the checks, commit the improvement. Then, separately, change behaviour. Two small safe steps rather than one large unverifiable one.

The reason lesson 3 came before this one is that a refactor without checks is a bet. You believe the extracted version does the same thing. Belief is not evidence, and the bugs introduced this way are the quiet kind - an off-by-one in a boundary you did not think about, a case that used to be handled by an accident of the old shape.

With checks, the loop is mechanical and almost boring: make one small change, run them, all green, keep going. If something goes red you undo the last change rather than debugging it, because you know exactly which change caused it - it was the one you just made.

This is also the moment the work of lesson 3 pays off. The checks you wrote to design the functions become the thing that lets you improve them for years afterwards. That is why test-first is not a chore imposed by someone else: it is the reason you can still change your own code six months later.

A comment explaining what a block does is usually a name asking to be born. If you find yourself writing '// work out the pages per hour', that block wants to be a function called pagesPerHour, and the comment can go, because the name now says it.

A variable called out, data, temp or result2 tells you the author had not decided what it was. Every one of those is a small tax on the next reader, who has to hold 'out means the totals so far' in their head while reading everything else.

A loop doing three unrelated jobs at once is harder to read than three obvious things, even though it walks the list only once. And a function you have to scroll to see is usually two or three functions that were never separated. None of these is a rule violation - they are hints. The judgement stays yours.

Pick the lines that do one identifiable thing. Ask what they need from around them - those become the parameters. Ask what they produce - that becomes the return value. Move them into a new function, name it after WHAT it produces rather than how, and call it from where they used to be. Run the checks. That is the whole move.

The most common hesitation is where to put the new function, and JavaScript settles it: function declarations are hoisted. MDN's page on the function statement says so and shows a function being called on the line above its own declaration. So you can put helpers below the function that uses them and read the file top-down - the important thing first, the details underneath.

Names deserve more thought than the mechanics. pagesPerHour says what comes back. calculateRate makes you ask 'rate of what, in what units'. doStuff is a confession. The best name is the shortest one that would let a reader skip the body entirely - because most readers, most of the time, should not have to open it.

Once extracting feels good it is easy to overdo, and the result is code where nothing happens anywhere. A function called addOne(value) that returns value + 1 has replaced something everybody understands with something they now have to go and look up, on the promise of a name that says no more than the code did.

The test to apply: does the name tell the reader more than the line it replaced? pagesPerHour(pages, minutes) does - it names a domain idea, and the arithmetic inside it is fiddly enough to be worth hiding. isPositive(value) barely does. addOne(total) does not, and it costs a jump to nowhere.

The other end of the same mistake is a helper with six parameters, which usually means you cut the code in a place where it did not want to be cut. If a helper needs half the surrounding function's variables to do its job, the seam is in the wrong place - put it back and look for a better one.

Useful way to hold it: a name is a promise about what is inside. best is a promise you cannot check - best what, by what measure? topTitle promises a title, chosen by being top of something. rate promises nothing at all; pagesPerHour promises a number in units you can say out loud.

Names are also where a domain lives. readlog talks about sessions, pages, minutes, tags and titles - not items, values, counts and strings. When the code uses the same words as the brief, the distance between what someone asked for and what you built is small enough to see across.

And when you genuinely cannot name something, that is information: it usually means the thing does not have one job. Splitting it until each piece can be named is not a naming exercise, it is a design one.

Refactoring changes shape and never behaviour, which is what lets your checks tell you whether you got it right - so refactor and change behaviour in separate steps. Look for comments that want to be names, vague variable names, and loops doing several jobs. Extract by asking what the lines need (parameters) and what they produce (a return value), and put the helpers underneath, because function declarations are hoisted. Stop when the name would say no more than the code it replaced.