Why Does This Exist?
Every class, function and field in the cart answers three questions: why is it here, what problem does it solve, what breaks if it is removed. A line that cannot answer them is cargo — it came from somewhere, it might be load-bearing, and nobody can tell.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
Pick any line of addItem — the find, the catalog check, the quantity field. Why does it exist, what problem does it solve, and what exactly breaks if you delete it — and how would you find out if you could not answer?
You have a working cart, half of it written by you and half pasted in from the reference after you got stuck. It works. You are asked to explain it in a review and you get to const existing = cart.items.find(...) and say "that is how you add items" — which is true and is not an answer.
Keep what works. The line is in the reference, the reference is correct, and removing things from correct code is how you break it; explaining every line is a luxury for people who have time. If pressed, "it is a best practice" covers most lines.
The code that works is the code you cannot change. When the maximum-quantity rule arrives, the line that needs to move is the find — and since "how you add items" is the whole explanation, there is no reasoning to move it with, so the rule gets bolted on somewhere else and the find is left alone as a superstition.
- The code that works is the code you cannot change. When the maximum-quantity rule arrives, the line that needs to move is the find — and since "how you add items" is the whole explanation, there is no reasoning to move it with, so the rule gets bolted on somewhere else and the find is left alone as a superstition.
- Cargo accumulates. A catalog check kept because the reference had it, a
createdAtkept because the tutorial had it, a try/catch kept because it seemed safe: none has an owner, none has a test that fails without it, and together they are a cart nobody can shrink. - "Best practice" is the sentence that stops the question. It is never wrong and never falsifiable; the practice it names was best for a problem, and the question was whether this is that problem.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Ask the three questions of one thing at a time — a field, a line, a function. Why does it exist: the rule, example or requirement that produced it. What problem does it solve: the wrong state that would occur without it, concretely. What breaks if removed: the example that fails, the test that goes red, or — the honest answer that matters most — nothing, which means it is cargo.
- Use the concept's own record as the answer key. The cart's
whyExistsentries say it for five things: quantity exists so that adding the same product twice is one entry with a count; the find before the append is the rule "one entry per product", encoded; the catalog check exists because total would fail later; the zero-becomes-removal exists because the rule is easier to keep than to check everywhere; priceOf exists because the catalog owns prices. Each entry ends with what breaks if removed. - Try the removal when the answer is not obvious. Delete the line, run the examples, watch which one fails. If none fails, either the examples are missing the case — write it — or the line is cargo. The experiment is a minute, and it replaces the argument.
- Where the line came from the reference or from a tool, the questions are the same and the standard is the same. Code you did not write is still code you own; the difference is that the "why" has to be reconstructed rather than remembered, and if it cannot be reconstructed the line is not understood (Understanding Is Not Delegable).
One line, the three answers, and the code it encodes
The rule device shows the full chain for the line most often kept as a spell: the invariant in words, the check in words, the check in pseudocode. Read bottom to top, it answers the three questions — the code exists because of the validation, the validation because of the rule, and what breaks without it is the rule's negation: duplicate entries.
rule One logical entry per product — the concept's second rule, discovered from the example add-again.
↓ becomes validation Before adding, look for an existing entry with the same product id; if one exists, increase it instead of appending.
existing = find entry in cart.items with entry.productId == productId
if existing exists:
existing.quantity = existing.quantity + quantity
else:
append { productId, quantity } to cart.items"We need this line" — climbed down
The why ladder is usually used on a technology claim — "we need Kafka". It works on a line. The claim here is the try/catch that arrived with the sentence "so the app does not crash", and the rungs walk it down to what was actually needed, which turns out to be the opposite of the line.
“addItem must be wrapped in try/catch that returns the cart, so the app does not crash.”
- ↓Why must it not crash? Because a shopper adding an invalid quantity should see a message, not a blank page.
- ↓Why would they see a blank page? Because an uncaught error in the UI event handler is not rendered. That is a UI fact, not a cart fact.
- ↓Why catch it inside addItem, then? No reason — inside addItem, catching hides the reject: invalid-zero returns a cart silently, and its test, which asserts a throw, fails.
the claim was right when A catch inside the operation is right when the operation itself has a recovery — a retry against a flaky inventory service in V5 — and even then it re-throws what it cannot recover from.
Detection questions for pasted code
Impl §77's detection questions, applied to the cart. They are the three questions in the specific form a reviewer or a tutor asks of code the learner did not derive — and the response to a blank is not shame, it is a route back to the concept stage where the answer lives (Why Is This a Map? — Detecting Cargo Cult and Routing Back runs the full flow).
"The find is how you add items. It is in the reference. It is a best practice to check before you push."
"The find encodes one-entry-per-product. Without it add-again produces two Laptop rows. It is where the maximum-quantity rule will go, because that rule needs the existing quantity."
The second explanation names the rule, the example that fails, and the place the next requirement attaches. The first is unfalsifiable and offers nothing to modify. A reviewer can check the second in one run of the examples; the first can only be believed.
The implementation ladder
Concept, examples, pseudocode, code, tests, production — for the concept this lesson is about. Code is the fourth tab, not the first.
Shopping Cart = A temporary collection of products the user intends to purchase, held between browsing and checkout.
- Does a cart have identity? Yes, weakly. Two carts with the same items are still two carts, because each belongs to someone and will become a different order. It needs an id once it leaves memory; in memory the variable is the identity.
- Who owns it? A shopper — a logged-in user or an anonymous session. The owner is part of the state because "my cart" has to be findable again.
- How long does it exist? From the first add until checkout or abandonment. Whether it survives a reload, a closed browser or a login is not a property of the concept; it is a persistence decision made later, and each answer changes where the cart lives.
- Should it survive reload? Usually yes for a store, usually no for a demo. V1 in memory says no; V2 browser storage says yes on one device; V3 server storage says yes everywhere the user is logged in.
- Should it survive login? Only if an anonymous cart and a logged-in cart are merged — a rule that does not exist in V1 and appears as a modification later.
- itemscollection of CartItemkeepThe cart is its items; without them nothing else means anything.
- items[].productIdidkeepThe reference to what is being bought. The catalog owns the product; the cart only points at it.
- items[].quantityinteger > 0keepTwo laptops is one entry with quantity 2, not two entries — the rule "one entry per product" needs a quantity to hold.
- owneruser id or session iddependsSo the cart can be found again by the person it belongs to.
- items[].productNamestringderiveIt would be convenient to render the cart without a catalog lookup.
- items[].pricemoneydependsThe total needs a price per item.
- totalmoneydropEvery screen shows the total.
- currencycodedependsPrices need a currency to be added.
- createdAttimestampdropAbandoned carts might be expired or emailed about.
- update Add item — the updated cart
- delete Remove item — the updated cart
- update Change quantity — the updated cart
- read View items — the list of entries — product id and quantity — for rendering
- domain Calculate total — the sum of price × quantity over the entries
- delete Clear cart — the empty cart
- • Every quantity is greater than zero.
- • One logical entry per product.
- • The total is never negative.
- • An unknown product cannot be added.
- • Quantity cannot exceed available stock — if inventory is enforced here.
How to do it
Most important first.
- Go through addItem line by line and write the three answers beside each one; there are six lines, and one of them — the return — takes a second, which is fine.
- For each field in the state, do the same; the concept's field verdicts (keep / derive / drop / depends) were this exercise done at the state stage (Challenging Unnecessary State).
- Where the answer is "I do not know", run the removal experiment before reading anything: delete, run the six examples, note which fail.
- Where the answer is "the reference had it", find the rule in the concept that the reference was encoding. If there is no rule, the reference has cargo too — it happens — and you have found it.
- In review, ask the three questions of one line of the other person's code rather than the whole diff; it is the question that teaches most per minute (A Review Checklist Worth Reading).
Worked on a concrete problem
The move has to produce something. This is what it produced.
- The find before the append. Why: the rule "one logical entry per product". Problem solved: without it every add appends, and the cart shows Laptop, Laptop, Laptop. What breaks: the example add-again — [ Laptop × 1 ] + add Laptop should be [ Laptop × 2 ] and would be two entries. The removal experiment confirms it in one run; this is the concept's predict-the-bug case.
- The catalog check. Why: an unknown product must not enter the cart. Problem solved: total would throw later on a product with no price, and checkout would sell nothing. What breaks if removed: no example in the concept's six — which is a finding about the examples, not the line. Write
[] + add "toaster" → rejected, and now the line has a test that goes red without it. - A
createdAtfield that arrived with a tutorial. Why: "abandoned carts might be emailed about". Problem solved: none in V1 — no operation reads it. What breaks if removed: nothing; the six examples and every test pass. It is cargo, and the concept's field verdict already said drop. It comes back with the requirement that reads it, not before. - A try/catch around the whole of addItem that swallows errors and returns the cart. Why: "so the app does not crash". Problem solved: it hides the reject — invalid-zero returns the cart silently instead of an error. What breaks if removed: nothing; what breaks if kept: the invalid example, whose test asserts a throw. Removal makes a test pass; that is the strongest possible answer to the third question.
How you know it worked
What now exists that did not before, and what question you can now ask.
- Every line of the operation has a rule, example or requirement beside it, or a note saying it was removed.
- At least one line was deleted this week and no example failed, and it stayed deleted.
- At least one line had no failing example when deleted, and an example was written so it does.
- "Best practice" has stopped appearing as an explanation; the sentence that replaced it names a rule.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?Which rule, example or requirement produced this line?
- ?What wrong state would exist without it — concretely, in the cart?
- ?Which example fails if I delete it — and if none does, is the example missing or is the line?
- ?For the lines I did not write, can I reconstruct the why, or am I keeping them because they were there?
What can go wrong
- Asking the three questions of the whole file. "Why does the cart exist?" has an answer and it explains no line; the unit is one thing at a time.
- Accepting "it might be needed later" as an answer to what breaks. That is a forecast; the cart's versions say when each thing arrives, and until then it is state nobody reads.
- Removing something because no example failed, without asking whether the examples are complete. The catalog check has no example and is load-bearing; the missing example is the finding, and the line stays.
- Treating the reference as exempt. It is the best answer the concept has and it is still code; the same three questions apply, and occasionally find something.
- Three answers per line for a six-line function is a page of notes for something that fits on a screen; most of it is thrown away once the answers are obvious.
- The removal experiment is destructive by design and needs the examples to be trustworthy first; run on a cart with three tests it proves less than it seems to.
- Asking the question of every line in review slows review; asked of one line per review, it is the cheapest teaching there is.
- "So every line needs a comment saying why." A line whose why is a rule reads as the rule when the rule is named well —
existingand// one entry per productin the reference is one comment for one non-obvious line. The questions are for the writer; comments are what survive of the answers. - "Delete anything without a failing test." Delete anything without a failing example after checking the examples are complete; the catalog check would be deleted by the first rule and kept by the second.
- "Cargo cult means copying code." It means keeping code whose purpose you cannot state. Copying with the purpose known is reuse; writing from scratch with the purpose unknown is still cargo.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALWhy does it exist, what problem does it solve, what breaks if removed — the three questions apply to any field, line, function, module or dependency, and the removal experiment applies wherever there are tests to run.
- TEAM-SPECIFICOn a team, the questions are asked in review, one line at a time, and the answers become the comments that survive; a solo learner writes them beside the code and discards most of them once the operation is understood.
- ILLUSTRATIVEThe six lines, the three tests and the tutorial's createdAt are for the shape of the argument; the five whyExists entries are quoted from the concept record.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto's review mode at /manifesto/review asks the three questions of every line before it is merged — why is it here, what does it solve, what breaks without it — which is this lesson as a habit.