What Naming Conventions Keep an Automation Maintainable?

What naming conventions keep an automation maintainable?

Names that say what the automation does, to what, and where. A workflow called Sync is useless in six months. A workflow called HubSpot to Airtable, new contacts, hourly can be understood by somebody who has never seen it, at the exact moment they need to understand it, which is usually during an incident.

This sounds like housekeeping and it is not. Naming is the cheapest documentation you will ever write, because it is attached to the thing itself and cannot drift away from it the way a separate document can. A good name is documentation that is impossible to lose.

I have inherited enough automation estates to have strong opinions here. The single best predictor of whether a system is maintainable is not how it was built. It is whether you can open the list of workflows and understand the business from it.

What should the name of an automation tell you?

Four things: the source, the destination, the trigger, and what moves. If a name carries those, somebody can decide whether it is relevant to their problem without opening it. That decision, made twenty times a week across a team, is where the real time is saved.

My preferred shape is source to destination, then the object, then the cadence. Stripe to Airtable, failed payments, realtime. Airtable to Slack, overdue cases, daily 9am. It reads slightly awkwardly and it is unambiguous, which is the correct trade in a list of forty items you will scan while something is on fire.

Avoid names that describe the intent rather than the mechanism. Keep the CRM tidy is a purpose, not a description, and purposes drift. The automation will still be called Keep the CRM tidy long after it has been repurposed to do something else entirely, and then the name is actively misleading.

How do you name the steps inside a workflow?

By what they do to the data, not by the app they use. A step called Airtable tells you nothing when there are five Airtable steps. A step called Find existing case by reference tells the next person what the step is for and what it should return.

The default names that platforms generate are the worst part of most inherited builds. Zapier, Make and n8n will all happily leave you with a chain of steps named after connectors, and reading that chain is like reading a sentence where every word is the same. Renaming the steps takes about five minutes and it is the highest-value five minutes in the whole build.

Be especially careful with steps that filter or branch. Those are the ones people misread under pressure. Name them by the condition, so Only if status is closed rather than Filter, because the difference between reading the name and opening the step is what decides whether someone makes a change at two in the afternoon or breaks something at two in the morning.

What about field and variable names?

Same principle, with one extra rule: never encode the current answer into the name. A field called is_approved_by_priya becomes wrong the moment Priya changes role. A field called approver_email survives the reorganisation. Names should describe the slot, not the thing currently occupying it.

The second rule is to keep one name for one concept across systems. If it is case_reference in Airtable, it should not be caseId in the script and Reference Number in HubSpot. Every translation between names is a place for a mistake, and translations accumulate silently because each individual one looked reasonable at the time.

When I built the automations that move case data for Ajust through Airtable and WhaleSync, the naming discipline across systems mattered more than any individual step, because the whole thing is a chain of translations. The same was true connecting HubSpot through Zapier for Kismet Health. Two systems that disagree about what something is called will eventually disagree about what it means.

Should the name include the owner or the system?

Include the system, not the person. Systems change slowly and people change fast, and a name with a former colleague's initials in it is a small archaeology problem for everybody who comes after. Ownership belongs in a field or a document, where it can be updated without renaming anything.

A prefix for the business area is worth having once you pass about twenty workflows. Something short and stable, so that sorting the list alphabetically groups related things together. It is a crude mechanism and it works, because most platforms give you a flat list and a search box and nothing else.

What I would avoid is a coding scheme that requires a key. If your names contain three-letter abbreviations that only make sense with a legend, you have moved the problem rather than solved it. The test is whether a competent stranger can read the name. If they need the legend, the legend will be lost.

How do you handle versions and retired automations?

Put the state in the name, at the front, where it cannot be missed. A prefix like OFF or OLD on anything paused or superseded stops somebody reactivating a workflow that was deliberately turned off. It sounds crude next to a proper versioning system and it is far more likely to still be in place next year.

Resist keeping two live automations named v1 and v2. Version numbers in names are a symptom of not having decided which one is real. If v2 works, turn v1 off and mark it. If you are genuinely running both, they are doing different jobs and should be named for those jobs rather than for their sequence.

Retiring something properly is its own discipline, and the name is only the first part of it. I wrote out the wider process in the piece on retiring an automation nobody uses. The naming part matters because a retired automation with a clear name is a record, and a retired automation with a vague name is a landmine.

What happens when you rename something that is already running?

Usually nothing breaks, but check what refers to it by name before you find out. Dashboards, log filters, alert rules, other workflows and anything you built that greps your own automation names can all be quietly dependent on the old string. The rename is safe. The things watching it may not be.

So rename in a quiet window, and rename in one pass rather than gradually. A half-renamed estate is worse than a badly named one, because now there are two conventions and no way to tell which items were missed and which were deliberately left alone.

Write down the old name somewhere alongside the new one for a few months. When an old alert fires or an old document is opened, that mapping saves somebody ten minutes of confusion, and it costs you one column in a spreadsheet.

How do you roll a convention out across an existing mess?

Start with the ones that wake people up. Rename anything that sends an alert or touches money first, because those are the automations people meet in an emergency, and an emergency is exactly when a bad name costs the most. The rest can follow whenever they are next opened.

Do not attempt a big-bang rename of everything. It is boring, it takes a day you will resent, and half of it will be wrong because you renamed things you had not looked at properly. Rename opportunistically instead: any automation you open for another reason gets renamed before you close it, which also spreads the work across the people already touching it. The same logic applies when you break a large workflow apart, which I covered in the piece on splitting one big automation into smaller ones.

The convention itself should fit in one short paragraph that lives next to the automations, not in a wiki three clicks away. If somebody has to go looking for the rule, they will guess instead, and guessing is how the second convention gets born.

What does a good convention look like when you are one person?

Exactly the same, and you need it more, not less. The dangerous assumption for a solo operator is that you will remember. You will remember for about three weeks. After that you are a stranger to your own build, and the names are all you have left.

There is a second reason, which is that being the only person who understands a system is a liability for you before it is a liability for the client. It limits what you can hand over, what you can take a break from, and what you can charge for, because unmaintainable work is worth less. I have written about that trap in the piece on being the only person who knows how it works.

The version I use for myself is deliberately plain. Full words, no abbreviations, source and destination in the name, state as a prefix. It looks unsophisticated in a list and it means I can open a client's account after four months away and be useful within a minute.

What should you do next?

Open your automation list and read only the names. Mark every one you cannot explain without opening it. That count is your maintainability score, and it is usually much higher than people expect, including for systems built by the person doing the counting.

Then rename the three that touch money or send alerts, and write your convention down in one paragraph next to the list. That is an afternoon of work that pays back the first time something breaks while the person who built it is unavailable.

If you have inherited an automation estate where nothing is named usefully and nobody is quite sure what is still running, reach out. Untangling that is a large part of what I do, and the first pass is usually faster and less painful than people fear.