Build Salesforce Conventions That Adapt to Change

I started as a developer looking for the one convention, one standard we would all follow, to rule them all. The right prefix, the right casing, the pattern that would keep the codebase clean forever. I was convinced it existed and I just hadn’t found it yet.

It took years of watching well-intentioned standards collapse to understand that the convention was never the problem. A standard without documented rationale and goals cannot be defended when someone challenges it. A standard without governance cannot be revised when change happens.

Durability comes from knowing why you chose the pattern, who owns it, and how to adapt it when conditions shift.

If you have inherited an org full of conventions nobody can explain, or watched a standard erode the moment its author left, you already know the problem. To address it, you need documentation and ownership strong enough to survive the next platform release, reorg, or resignation.

Map the conventions already in your org

Before choosing conventions, start with understanding which decisions have already become conventions. If your org is like most, then fields, objects, list view names, report and dashboard folders, permission sets, and email templates are already following some implicit standard someone established before documenting it. The frameworks you pick, the libraries you adopt, and the working agreements your team follows all bring conventions of their own.

Trigger framework conventions are one example. Three generations exist in the wild: the first embedded logic directly in triggers, the second introduced handler classes where the suffix doubles as a runtime application programming interface (API) lookup, and the third moved conventions into metadata records entirely. The framework you implement influences where conventions live, and switching later means migrating the conventions too.

Library patterns impose their own standards. For example, the FinancialForce Library (fflib) organizes Apex into layers, with queries in selector classes, business logic in service classes, and record behavior in domain classes. Each class extends a base class for its layer, and the class name carries the layer as a suffix, so AccountsSelector queries accounts and AccountsService holds their business logic.

In contrast, SOQL Lib, a query builder for Salesforce Object Query Language (SOQL), uses a method-based convention, with by methods such as byRecordType adding filters and to methods such as toList returning results.

Working agreements are conventions too, and they show up in metadata the same way a trigger framework does. A Definition of Done requiring every Apex class to ship with a matching test class is what puts AccountsServiceTest next to AccountsService.

Backlog conventions end up in names you cannot easily rename later. A story title or ticket key sets the branch name, and that branch and its commits stay as named. Compare ten stories against the branches they produced and you will see whether a convention exists.

Write down what each convention must accomplish

Choosing a pattern before defining the goal is where many convention efforts go wrong. The specific pattern you land on matters less than the job it must do.

Write down what each convention must accomplish. “Flow names must make the triggering event and object visible from the Setup list, because flow names appear in debug logs and error emails without their metadata columns” is a goal. “Flow names must be consistent” is not.

The goal of the trigger framework’s handler suffix is to give the bypass API something to key on, and the goal of the fflib layer suffixes is to let you tell a query from business logic without opening the class.

Each goal drives a different set of choices and gives the team a way to evaluate options against criteria rather than relying on consensus.

Weigh each convention against everyone who uses it

Casing has a direct artificial intelligence (AI) cost. Testing with tiktoken shows Title_Snake_Case, the Setup default, costs roughly 67% more AI model tokens on both input and output than PascalCase for long multi-word identifiers, an admittedly extreme example.

Extrapolated across all code, that overhead is informally called the snake_case tax. For teams invested in Agentforce or agentic development, that overhead accumulates across every field name, action label, and description an agent processes, at runtime and in the editor.

Developer ergonomics favor PascalCase. Developers from Java, C#, JavaScript, and Apex read and write camelCase and PascalCase by default, with Salesforce Multi-Framework bringing in more outside developers who may need to second-guess the reasons for casing inconsistency. Usually, typing an underscore requires holding down the Shift key then pressing another key between every word.

Admin ergonomics instead favor Title_Snake_Case. The Setup user interface (UI) generates it automatically from the label. Type ‘Account Manager Name’ as a field label and the API name becomes Account_Manager_Name__c with no extra steps.

Where no label exists, such as expression set variables and decision matrix columns, the dropdown gives admins the API name, so the underscores aid scanning without adding creation overhead. Adopting PascalCase means asking admins to strip underscores from every field they create.

Title_Snake_Case orgs are rarely deliberate. They are the Setup UI default, auto-generated from the field label. Whether you keep it or change it, write down why. That decision is a convention, and leaving it undocumented means every person who creates a field may want to make it differently.

Weigh these costs, and the answer follows from your goals, not your preferences. The same costs with a different ranking may provide a different answer. AI cost, developer ergonomics, or admin readability are all legitimate considerations when choosing a casing convention; not examining any of them is the problem.

Make decisions with a framework, not a vote

Naming decisions made by consensus produce the result that offends the fewest people, not necessarily the one that best fits the context. They reflect the mood of the day and who was in the room, often only retrofitted to a project after their absence has lost the team time. As Tuckman wrote in 1965, “In the task realm, intimate, personal opinions are expressed”, a subjective feeling which can influence a show of hands and be forgotten after lunch.

Moods change, people leave or go on vacation, and today’s influences such as product direction may not be the same in a year’s time. Without a framework to guide conventions, you end up with a lineage of the fashion of the day. As a Salesforce Architect, you have likely found inconsistency due to functionality being added at different points in time.

Your Salesforce org does not have to experience the same traceable naming evolution. You own it, so whereas a public API carries its history forward, you can mark historic names deprecated and migrate the org off them.

A weighted decision matrix separates the decision from the politics. List the criteria that matter to your org, assign weights based on your documented goals, score each option against each criterion, and let the ranking surface. 

Salesforce Decision Guides tackle architectural choices the same way, working through explicit criteria and tool comparisons rather than settling them by preference, and they are worth reading as a model for structuring a convention decision.

Consider the enforceability of conventions

Enforcement feasibility belongs among the matrix criteria. It asks whether the convention can be verified by a continuous integration (CI) tool or deployment checklist. Conventions sit on a spectrum from systematically enforced to purely advisory.

PMD (a name, not an acronym) can verify naming patterns in Apex classes, allowing for bespoke rule creation. Metadata conventions, like requiring every custom field to carry a description, need static analysis of the metadata itself, run as a CI check or a Salesforce command line interface (CLI) predeploy hook. At the advisory end, a standard enforced only by code review holds as long as reviewers check it.

Know where on that spectrum a convention sits before committing to it. A convention with no automated enforcement path requires stronger governance to survive team turnover.

AI-assisted development compounds deviation, with a coding agent having no awareness of informally held conventions. It works from training data and whatever context is in the prompt.

Consider the reversibility of the conventions you pick

Reversibility belongs among the criteria too. It asks what it costs to undo the decision if it turns out to be wrong. A naming decision at the start of a project is effectively free; two years into production with integrations and a managed package, it becomes a coordinated migration.

Rename a custom field and every SOQL query in an integration, every Flow reference, and every managed package that includes it can break. Integration partners hardcode field API names in their systems. Renaming a handler class in the Kevin O’Hara trigger framework breaks the bypass contract with no compiler error.

Document your selected style

After the decision, record it. Architecture Decision Records (ADRs), popularized by Michael Nygard in 2011, capture the context at the time of the decision, the decision itself, and its consequences.

An ADR is not just documentation. It makes reversal easier to evaluate because it records the assumptions the decision rested on. When a convention needs to change, the challenge targets those assumptions, not the person who made the call.

Where decisions live is a convention decision too. ADRs in a Git repository travel with the code and benefit from pull request review, while a wiki such as Confluence reaches stakeholders without repo access at the cost of one more system to keep in sync with what is deployed. The location determines who reviews the decision and how quickly it drifts from the codebase, so write down where your decisions live and why.

Govern conventions with review dates and a reversal process

Every convention has an implicit shelf life. What was a reasonable standard in 2021 may be actively harmful in 2026.

Build review triggers into decisions when you make them. “We are using this prefix scheme because we cannot namespace these components yet. Review when we migrate to unlocked packages.” This is an example of a useful justification to document in your ADR, rather than in someone’s memory.

Stable decisions can follow a fixed cadence and be reviewed quarterly. The Salesforce Center of Excellence model shows how a Center of Excellence (CoE) governs standards across the org, providing a  home for metadata naming alongside integration standards and release processes.

Your team needs a predefined process for appealing and reversing decisions following changes in circumstances or available information. The alternative often becomes silent rebellion, undermining governance and creating unnecessary friction.

The challenger writes a short Request For Comments/Change (RFC), a common way to solicit feedback on ideas, documenting the problem and proposing an alternative. The RFC is reviewed. If approved, the original ADR is marked superseded and a new ADR records the revised decision.

The challenger then attaches a migration plan covering the affected metadata, the timeline, and who owns the rename work.

Make it concrete. A team standardized on Title_Snake_Case for custom fields in 2022 and recorded the decision in ADR 0042. Two years later they move heavily into Agentforce, and the token cost the original ADR never weighed starts to bite.

A developer raises an RFC proposing PascalCase for new fields, citing the measured overhead. The accountable architect approves it, and a new ADR 0051 supersedes 0042. The migration plan scopes the change to new fields only, so no integration or managed package breaks.

If your team is standing up governance for the first time, the Essential Habits for Salesforce Admins module on Trailhead can help you establish and enforce governance and design standards, including when to form a Center of Excellence to hold that accountability.

Start with what you know, then write it down

I never found the one convention to rule them all. That was the wrong question.

The right question is whether you can explain why you chose the one you’re using and how to adapt it when conditions shift. This starts by auditing and documenting the conventions you already have. The decision matrix and the ADR template come next.

Be intentional, be explicit, be rational, and be willing for your choices to eventually be proven wrong.