Choosing a shape for your data

Up to now you have mostly been handed values one at a time: a number here, a piece of text there. Real information does not arrive like that. It arrives in clumps. A customer is a name and an email and a delivery address and a list of past orders, all at once, all belonging together.

The SHAPE of some data is the decision you make about how those facts sit next to each other in your program: which facts are grouped, what each group is called, and which parts are lists. Nothing more mystical than that. When a developer says "what shape is that?", they are asking you to describe the arrangement, not the contents.

You can describe a shape out loud before you type anything, and you should. "An invoice is an id, a currency, and a list of lines; each line is a description, a quantity and a unit price." That sentence is a design. Everything after it is transcription.

This module is about making that decision well, because it is the one decision that is expensive to change later. A wrong variable name costs you thirty seconds. A wrong shape costs you every function that touched it.

An array is a numbered queue. The things in it are the same KIND of thing, and their positions mean something: first, second, third. You can ask how many there are. You can add one to the end. What you cannot sensibly do is ask the queue for "the email address", because position 2 is not the email address of anything — it is just whoever is standing second.

An object is a filing cabinet with labelled drawers. Each drawer holds a different KIND of fact, and the label is how you find it. You ask for the drawer marked "email" and you get the email. What you cannot sensibly do is ask a filing cabinet how many drawers there are and expect that number to mean anything, or ask for "the third drawer" — the labels are the point, the order is not.

Almost every shape you will ever design is these two, nested inside each other. A filing cabinet with a queue in one drawer. A queue of filing cabinets. That is it.

A LIST is an array of same-kind values: ["London", "Paris", "Rome"]. Reach into it by position with square brackets, count it with .length, and expect the order to matter or at least to be stable.

A RECORD is an object whose named properties are different facts about one thing: { from: "London", to: "Rome", nights: 4 }. Reach into it by name, with a dot (trip.from) or with brackets when the name is itself in a variable (trip[fieldName]).

A TABLE is an array of records — a list of things that all have the same named facts. This is the workhorse. Rows of a spreadsheet, results from a search, items in a basket, replies to a form: all tables.

You will also meet a fourth, which lesson 3 is entirely about: a LOOKUP TABLE, an object whose property names are ids rather than field names. It looks like a record but it is doing a different job, and confusing the two is worth avoiding early.

Question one: are these values the SAME kind of thing as each other? Three city names are the same kind of thing. A city name and a number of nights are not. Same kind means array. Different kinds means object.

Question two: would I ever want to say "the next one" or "how many"? If yes, you need positions and counting, which is an array. If instead every value has its own name and asking for "the next one" is meaningless, it is an object.

Run both questions over the sentence you said out loud. "An invoice is an id, a currency, and a list of lines" — id and currency and lines are different kinds, so the invoice is an object; the lines are all the same kind and you will certainly want to count them, so lines is an array; each line is a description and a quantity and a price, different kinds again, so a line is an object. The whole shape falls out of two questions asked three times.

When both questions genuinely tie, prefer the array of records. It is the shape that survives the most changes, and the next section says why.

The single most common beginner shape is two arrays side by side: one of names, one of scores, where names[0] goes with scores[0]. It reads fine and it works fine, right up until it does not.

The problem is that nothing in the program knows those two arrays are related. Remove one name and the scores do not shift with it, so from that moment on every pairing after the removal is silently wrong. Sort one and the other keeps the old order. Add a third fact and now three arrays have to be kept in step by hand, forever, in every function anyone ever writes.

The fix is one line of thinking: if two values belong to the same thing, put them in the same thing. One array of records instead of two arrays of values. Now removing a person removes their score too, because the score was never separate from the person in the first place.

This is sometimes called parallel arrays, and you can recognise it from across the room: any time you see two arrays indexed by the same variable, ask whether they should have been one.

A good shape makes the change you are about to make small. If a customer's records live in one object, adding a phone number touches one place. If they are smeared across four parallel arrays, it touches four places and every loop that walks them.

There is no perfect shape, only a shape that suits the questions you will ask. If you always fetch a person by id, an object keyed by id makes that a single step. If you always show people in order, an array does. You will meet both in this module, and converting between them is cheap once you can see which one you have.

The reason to think about this now, before frameworks and databases and APIs, is that all of those are just other people's opinions about shape. Once you can describe a shape and defend it, reading their documentation stops being a memory exercise.

A shape is your decision about how facts are grouped and named. Same-kind values that you count or order go in an array; different-kind facts about one thing go in an object with names. An array of records is the workhorse shape. Two arrays that must be kept in step by hand is a bug waiting to happen: put values that belong to the same thing inside the same thing.