Choose the wrong word in a software project, and you may live with its meaning for years

Early in a project, someone writes a requirement: this feature can be locked.

Or was it disabled?

To the person writing the requirement, the two words might mean the same thing. To a developer, they don’t.

Disabled usually reads as: the function is switched off and can’t be used. Locked reads more like: the function still exists, but something is preventing access - and presumably something can unlock it again.

So you get two perfectly reasonable implementations of one ambiguous word.

The part nobody plans for is that words travel. Requirement, code, API, database, UI, documentation. Five developers later, the word’s meaning has become part of the system - not the meaning the author intended, but whatever the first reader assumed it meant.

I’ve run into this pattern again and again over twenty-five years of building software. Integrations where both systems used the same term for different things. Hardware/software interfaces where “ready” turned out to mean three different things to three different disciplines.

The problem is rarely that people use different words. The bigger problem is when they use the same word and believe it means the same thing.

Over the years I’ve developed a fairly boring habit: before a complex project gets moving, agree on what the central words actually mean. The states, the entities, the events.

Not a hundred-page document - just enough that locked, ready, completed and approved mean the same thing on both sides of an interface.

It looks like administration. In my experience it’s architecture.