Naming Convention

When several people name things, the names drift apart on their own. The developer working on the web app writes doc_shared for document sharing, the developer on mobile writes shareDocument for the same action, and a browser extension added later sends Document Shared. Each of them simply carried over the style used in their own code.

The drift only shows up when someone tries to count. An event is a single line recording who did what and when, and counting those lines only works if the same action carries the same name every time. Ask how many times documents were shared last month and the analytics tool returns the count of lines tagged doc_shared. Lines stored under the other two names are treated as a different action and drop out. The answer comes back smaller than reality, and nobody notices it was smaller until much later.

In practice the problem surfaces as a question answered with a question. Mia asks how much sharing grew last month, and Theo asks back which name she means. Getting one number starts with reconciling a list of names, and only the person who did that reconciling trusts the number.

A naming convention is a few lines of rules written down to prevent that split before anything is instrumented. It isn't a device for producing good names — it's a device for making sure a name can only come out one way. Choosing what to record is the job of the tracking plan; deciding what shape the chosen names take is the job of this rule.

Five items usually cover it, and the whole thing fits on one screen.

1. Casing — decide once whether names use lowercase with underscores or run words together with capitals. To an analytics tool, doc_shared, docShared and DocShared are three separate names, so settling this one question removes half the drift.
2. Word order — fix the positions, typically object first and action second. Lining names up as doc_shared, comment_added and invite_sent means that sorting alphabetically groups everything about one object together.
3. Tense — a record describes something that already happened, so verbs are kept in the past tense. If share, shared and sharing all appear, names split three ways even when the first two rules are followed.
4. Word list — keep exactly one word per thing. If doc, document and file all circulate in the same product, names diverge even when the format matches. Roughly ten standard words are written down, and this is also where the convention lines up with terminology consistency, the rule that the product interface always calls one concept by the same word.
5. Property naming — the same rules apply to event properties, the extra fields attached to a recorded line, such as the sharing method or document type stored next to the fact that something was shared. One extra item shows up here: put the unit in the name. Write duration on its own and the only person who knows whether the value is seconds or milliseconds is the one who instrumented it.

A line about what must never appear in a name usually goes in too. Values that identify a person, such as a user's email address, get blocked here.

The people who write it sit on the data side; the people who read it are the developers who instrument the records. A company of around forty has no dedicated data owner, so the product manager who owns a feature also decides how that feature is recorded. At Pagedeck, Mia drafts the rules and Theo checks that the code actually writes names that way. When nobody who does the instrumenting is in the room, the rules come out awkward to follow, and awkward rules are ignored within two months.

Readers fall into three groups.

1. A developer about to instrument something — the most frequent reader by far. The same action may leave the user's device through client-side tracking or leave the server through server-side tracking, and the name has to match even though the sending point differs.
2. Whoever builds the metrics — they should be able to guess what a line counted from the name alone. In a product where the rules held, collecting every name that starts with doc_ is enough to gather everything about documents.
3. Anyone who joins later — long after the person who invented a name has left, a surviving convention is what makes the old names readable.

Because it gets read right before someone writes code, the document has to stay short. Once it runs past one screen, people start instrumenting without opening it. It also helps to name one person who reviews proposed names, since a rule with no reviewer stays a document and never reaches the data.

"Can you match the convention on that event name? Object first, then the action."

The name isn't wrong in substance — the shape is off and should be fixed before it ships.

"That one predates the convention, which is why it reads like that. We're leaving it alone."

Renaming it would cut the line off from the history already recorded under the old name.

"Please put the unit in the property name. duration_sec rather than duration."

Make it possible to tell seconds from milliseconds by reading the name.

At Pagedeck, Theo sends Mia a one-line list of candidate names before instrumenting a new feature. Review takes about five minutes, and names that break the rules get caught before they reach the code. When the break is found afterwards, the fix isn't a rename: the old and new names go into the tracking plan as a pair that has to be read together.

The most common mistake is treating it as a matter of formatting taste. Underscores or capitals read the same way to a human, so it feels fine for each team to pick its own. But the counting is done by an analytics tool, not a person, and a single different character makes it a different event. Leave it alone and six months later answering "how often was a document shared" means hunting down three names and adding them up, with no signal at all when one of them is missed. This is not the same problem as data loss, where records never arrive because of blockers or errors. Here every record arrived; the side doing the counting just can't find it.

The other frequent belief is that names can be cleaned up later. They look like text, so a one-line code change seems enough — but the names on records already stored are never rewritten retroactively. The metric breaks on the day of the change, and comparing this month against three months ago then requires an exception that reads two names as one.