Principles¶

The standards on this site rest on a small set of principles. Every page in Code Standards and Metadata Standards is an application of them, and when a specific standard is silent, these principles decide the question.

Core Principles of Salesforce DevSecOps¶

DevSecOps makes security a part of every step of development and operations, instead of a check made once, just before a release. These principles shape how these standards apply it to Salesforce.

• Shift left. A problem is found at the earliest point that can find it. Security is considered when a change is designed, the editor and the commit hook check a change before it leaves the developer's machine, and the pull request gates check it before it is merged (Local Checks Before the Push, Quality Gates). A finding then reaches the developer while the change is small and its context is fresh.
• Automate the checks. Every check that a tool can make runs in the pipeline, on every change, the same way each time: static analysis of the code and the metadata, secret scanning, the scanning of dependencies for known vulnerabilities, and the tests (Standards Are Enforced, Not Hoped For). People review what a tool cannot judge.
• Share the responsibility. Security is not a separate team's last step. Developers, administrators, security specialists, and operations staff work from the same standards, the team that owns a part of the system reviews its changes, and the Centre of Excellence keeps the standards (A Centre of Excellence).
• Monitor continuously. Security does not stop at the deployment. The org is checked on a schedule for changes made outside the pipeline and for failing tests, its activity is audited, and its logs go to an observability platform (Org Surveillance, Audit Continuously, Observability).
• Everything in version control. Version control holds as much of the system as it can: the code and the metadata, and also the workflows, the rulesets of the scanners, the settings of Prettier and ESLint, and the rulesets that protect the branches. Each of them is then reviewed, versioned, and restored like code (Version Control, Appendix C). The exception is Tier 0 metadata, such as certificates, which never enters version control (Tier 0).
• Fast, readable feedback. A developer reads every result on the pull request, as a table that separates what blocks from what is advisory, and never has to search a log for it (Quality Gates, Developer Feedback Quality and Shift-Left Visibility). Top priority gate results can be sent via Slack. Feedback that is quick to find is quick to act on.
• Secure the pipeline itself. The pipeline can deploy to every org, so it is protected like production: its secrets stay out of the code, the files that configure it change only with the review of the team that governs it, and the packages and actions that it runs are kept up to date (Secrets Management and Security Scanning, Supply Chain Security, Renovate and Dependabot).
• Separation of duties. No one person both makes a change and approves it: every change has the approval of at least one other person. These standards govern both the org's metadata and the pipeline that delivers it, and different people hold each. For example, the team that administers the pipeline does not write or approve changes to the org's metadata. Similarly, developers, architects, and release managers who change the org do not change the pipeline or the standards without that team's review (Repositories, A Centre of Excellence).
• Traceability. Every change reaches a protected branch as a reviewed pull request, with a title in the Conventional Commits form, so the history and the changelog say what changed in each release, why, and who approved it (Pull Requests, Release Please).
• Measure and improve. The pass rate of each gate, the time that a pull request takes to merge, and the health of the tests are measured over time, so the organisation can see whether its quality and security improve, and where to act next (Measuring DevSecOps Maturity).

Expected Outcomes¶

An organisation that follows these principles can expect these results.

• Faster releases. Automated checks on every pull request find a security problem while the change is still open, so it does not hold up a release at the end. A release is then a step that the pipeline has already proven, not a review that starts late.
• Lower costs. A problem fixed while a change is being written costs the least: the developer still has the context, and no user, data, or release depends on it yet. The same problem found after deployment, or in a breach, costs much more to find, fix, and explain.
• Easier compliance. Every change reaches the org through a reviewed pull request, so version control holds a record of who changed what, when, why, and who approved it. With the audit of activity in the org, that record is the evidence that an auditor asks for.
• Less downtime. A change that would break the org is stopped at a gate, and the org is checked on a schedule, so fewer problems reach users, and those that do are found sooner (Platform Uptime, Org Surveillance).
• Smaller data exposure profile. Users hold only the access they need, records are private by default, and secrets stay out of the code, so a mistake or an attacker reaches less (The Principle of Least Privilege, Object Level Security).
• Consistent quality. Every repository runs the same checks from the same shared configuration, so code and metadata meet the same standards whichever team or org they come from (Governance at Scale).
• Focused and efficient checkpoints. The tools settle formatting and the mechanical rules, and the gates block only what matters, so a reviewer spends attention on design and intent, and an approval is quick when nothing needs it (Severity Levels).
• Faster onboarding. A new developer or administrator gets the standards, the tools, and their settings with the repository, and the checks show the standards at work from the first change (Packages and Their Configuration Files).
• More productive administrators and developers. Problems found early, formatting done by a tool, and results that are easy to read mean less rework and fewer interruptions, so more time goes to the work that the business needs.

Fundamental Requirements for Salesforce Org Operations¶

Some requirements are not traded against schedule, scope, or budget. A change that fails one of them is not finished, whatever approvals it holds:

• Accessibility. Everything built on the platform meets WCAG 2.2 Level AA, for all internal and external users. See Accessibility for why that standard and that level, and for the United States and Australian laws that require it.
• Security. User permissions are minimal, the org is checked for data that should not be there, every change passes the security gates in the pipeline, and secrets never enter version control. See Section 7 and Permissions and Security.
• Observability. Every automation layer logs through one framework, and logs leave the org for an observability platform. See Observability.
• Version control as the source of truth. Every change reaches the org through the pipeline. See Section 4.

Priorities¶

When concerns compete, they are resolved in this order, from most important to least. A lower priority never justifies weakening a higher one. The Fundamental Requirements for Salesforce Org Operations above still apply to every change whatever its rank: accessibility, for example, ranks fifth when concerns compete, but no change ships without meeting the WCAG 2.2 Level AA baseline.

1. External Security¶

Nobody gets in from outside. Experience Cloud sites and their guest users, malicious URLs and open redirects, injected markup and script, weak password and session policies, and exposed integration credentials are all ways in, and closing them comes before everything else. The principle of least privilege applies here first: guest users, community users, and integration users hold only the access their purpose requires, so that anyone who does get in can reach as little as possible.

2. Internal Security¶

Nobody sees a record they should not see. The principle of least privilege governs every grant of access: sharing, object and field permissions, and user-mode data access ensure that every authenticated user, internal or external, can reach exactly the records and fields their role requires, and nothing more. See Permissions and Security.

3. Platform Uptime¶

Every feature works, all the time. Code and automation stay within governor limits and shared org allocations, such as the platform event limits, so that one process cannot exhaust a limit and stop others from running.

4. Proven Functionality¶

Every automation and process is proven to do what it is meant to do. Tests exist to demonstrate behaviour, not to reach a coverage number. The principles behind this priority are Determinism, that the system works as designed every time, and Testing, that behaviour is proven, not assumed.

5. Usability and Accessibility¶

Everything built on the platform is easy to use, for everyone. Pages, components, and screen Flows are clear and consistent, and they work for people using assistive technology. Accessibility never falls below the WCAG 2.2 Level AA baseline; above that baseline, usability and accessibility improvements give way only to the four priorities above.

6. Platform Speed¶

Code is efficient. Speed matters, but it ranks below security, uptime, proven functionality, and usability: secure code that stays within limits and runs smoothly is preferred over fast code that runs badly.

99. Business User Priorities¶

The number is deliberate: many other concerns come before this one. Business priorities are a real consideration, and they decide what gets built and when. They never decide how a change reaches the org. No metadata is pushed through unchecked or unapproved because someone on the business side wants it done now: every change goes through the same reviewed, tested pipeline, whatever its urgency.

General Considerations¶

Some considerations apply to every decision in every Salesforce org, whatever its rank in the list above. They overlap with the priorities deliberately: the priorities decide which concern wins when two compete, while these considerations are weighed in every design, every build, and every review.

Platform Limits¶

Governor limits and shared org allocations are design constraints from the start, not problems to fix after they are hit. Code and automation are bulkified, and every process is designed for the volumes it will meet in production, not the volumes it meets in testing.

Large Data Volumes¶

Every org is treated as a large data volume org, and built accordingly. An org that is small today may not stay small, and a design that works on thousands of records becomes difficult to change once it holds millions. Queries are bounded from the start: every query has a filter or a LIMIT, so that it still runs when the object is large, and a filter on an indexed field keeps it selective (Queries).

Usability and User Experience¶

Every page, component, and screen Flow is clear, consistent, and fits the way people work. Standard Lightning components and Lightning Design System patterns come before custom ones, so the org behaves the way its users expect.

Accessibility¶

Everything built on the platform conforms to WCAG 2.2 Level AA, for all internal and external users. See Accessibility.

Efficiency¶

Code and automation are frugal: they use no more of the platform than they need, so no more queries, DML operations, CPU time, or storage than the job requires.

Speed¶

Every process takes no longer than the work requires: a page loads, a record saves, and a job finishes in as short a time as it can. Speed is a separate concern from efficiency, because a process can use few resources and still make the user wait. Speed ranks sixth among the priorities (6. Platform Speed).

Extensibility¶

Every decision is made with an eye towards future growth. No decision is made that would prevent the org, its data model, or its automation from scaling smoothly as the business grows.

• Decisions are made as if the org held large data volumes and served several independent business units, even when it does neither today (Large Data Volumes). The org is built for the complications that nobody can foresee yet, not only for the ones that are known.
• A design leaves room for the next requirement. A new business unit, region, record type, or integration is added to what exists; it does not force a rebuild.
• A choice that is hard to reverse is made with care. A relationship type, a field type, or a sharing model that suits today but blocks tomorrow costs a data migration to change.

Maintainability¶

Everything in the org can be changed safely by someone who did not build it, long after it was built, and the cost of a change stays small as the org grows.

• A change is made in one place, because logic that two places need lives in one class, one subflow, or one set of custom metadata records (Reuse).
• Code is readable and documented, and every piece of metadata carries a description of what it is for, so that the next person can understand it before changing it (Readability, Documentation).
• Tests show at once when a change breaks something (4. Proven Functionality).
• Complexity is kept low, so that each piece can be understood on its own, and unused code is removed (Complexity and Unused Code).
• Retired features are removed, not left for the next person: Workflow Rules and Process Builder processes are rebuilt as Flows (Workflow & Process Builder), and inactive Flows are deleted.
• Code stays on a current API version, so that no part of the org depends on behaviour that Salesforce has since changed (API Version).

Complexity rules count what makes code hard to follow: the paths through a method, how deeply it nests, how long it is, and how many fields a class holds. A count is a signal for a reviewer, not proof of a problem, so these standards keep the complexity rules below the level that blocks a pull request. For Apex, PMD's cognitive and cyclomatic complexity rules and its rule on deeply nested if statements report at severity 3, and its rules on the length of methods and classes and the number of fields in a class report at severity 4; each points the reviewer at code that may need to be split (Complexity and Unused Code). For JavaScript, ESLint's rule on nesting depth reports at severity 3, and its rules on cyclomatic complexity and on the length of a function report at severity 4 (JavaScript: Complexity). These standards set no limit on the number of parameters of a method, in Apex or in JavaScript, and they leave out ESLint's rules on the number of statements in a function, the length of a file, and nested callbacks (max-statements, max-lines, max-nested-callbacks, and max-params). Code Analyzer ships all of these rules, and an organisation may switch any of them on, or change its threshold.

Readability¶

Everything in the org is written for the next person to read it, who may not be the person who built it. This holds for code and for metadata alike.

• All code is readable and documented.
• Every object, field, Flow, permission set, and other metadata component carries a description of what it is for.

Code and metadata that explain themselves can be reviewed, audited, and safely changed by someone who did not build them.

Reuse¶

Code and metadata are built once and reused, not copied. Logic that two places need lives in one class, one subflow, or one set of custom metadata records, and each place calls it, so that a fix or a change is made in one place and reaches every caller.

Security Principles¶

The Security page holds one of them in full: nothing secret is in version control.

The Principle of Least Privilege¶

Every user, integration user, and guest user holds the minimum access their work requires, and nothing more. This is the principle of least privilege (PLP), and every standard on this site that concerns security, permissions, or access applies it. Least privilege underpins both external security and internal security: it limits what an intruder can reach, and it limits what each legitimate user can see.

• Access is granted through permission sets and permission set groups, and through the platform's other built-in access controls, never through workarounds.
• A field is never hidden through the user interface as a way of restricting access. A field removed from a page layout or a Lightning page is still visible in reports, list views, search, and the API; access to it is restricted with field-level security.
• Delegated administrators handle defined administrative tasks, such as managing users, for their own groups, so that those tasks do not require full administrator access.
• Permissions are audited regularly, and access that is no longer needed is removed.
• Code follows the same principle. A class keeps its methods and variables private, and opens one only when code outside the class has to call it (Apex: Access Modifiers).

Protect the Data¶

Security is fundamental, and it covers the data as well as the access to it. Every field is classified with its Field Usage, Compliance Categorization, and Data Sensitivity Level, so that the org knows what each field holds and how it must be protected. User permissions are kept minimal, and the org is checked regularly, and in real time, for data that should not be there, such as payment card numbers or government identifiers typed into free-text fields. Salesforce Shield provides the tools for this; see Platform Monitoring with Salesforce Shield.

Audit Continuously¶

What people do in the org is audited, not only what they are allowed to do. Activity such as creating, running, and exporting reports is monitored alongside configuration changes and permission assignments, so that misuse is visible and investigations have a trail to follow.

Supply Chain Security¶

Supply chain security is essential. Every proposed change comes with a written explanation of what it changes and why, including every new or updated dependency. Every piece of JavaScript is analysed: the JavaScript in the org, including third-party libraries bundled in static resources, and the JavaScript in the GitHub automations that build and deploy it. See Section 7.

Secure by Default¶

The default is the safe choice, and the exception is explicit and reviewed. Apex classes declare their sharing, and database operations run in user mode; a system-mode operation is a deliberate, justified exception that is flagged for review wherever it appears.

Governance Principles¶

A Centre of Excellence¶

The organisation has a Salesforce Centre of Excellence (CoE). Its functions are beyond the scope of these standards at this time.

Standards Are Enforced, Not Hoped For¶

Quality and security are properties of the system, not aspirations of the team. A rule that depends on human discipline degrades under deadline pressure; a rule enforced by the platform does not. So every standard on this site answers two questions: what is required, and what enforces it. The enforcement is a branch ruleset, a required status check, a static analysis rule, or a metadata check that runs in the pipeline and cannot be skipped.

Apple's "goto fail" bug of 2014 shows the difference. One duplicated line under an if with no braces switched off a signature check in iOS and OS X, and it shipped unnoticed. A rule that requires braces, run on every change, would probably have prevented it (Braces).

A secure, auditable org is the outcome of this approach rather than a separate task. A pipeline that admits only approved changes, code that meets the code standards, and metadata that meets the metadata standards together produce an org whose security can be demonstrated, not merely asserted.

Every Rule Has a Standard, and Every Standard Has a Rule Where One Is Possible¶

A standard (or policy) is the plain-language statement of what matters. A rule is the implementation that enforces it, such as a PMD rule (written in XPath or Java) or a pipeline check. The relationship is many-to-many, with two constraints:

• Every rule enforces at least one documented standard. A rule with no standards behind it is noise that teams learn to suppress.
• Every standard is enforced by at least one rule, wherever an existing tool such as static code analysis can enforce it. A standard that a rule could enforce, and that has none, is an aspiration.

Not every standard can have a rule. No static analysis rule can tell, for example, that two queries could have been one. Such a standard is still a standard: it is stated like any other, and reviewers check it. Some of these standards are blocking, as a severity 1 or severity 2 rule is: a violation is grounds for a reviewer to reject the pull request. An AI tool may be able to check more of them; that is beyond the scope of these standards at this time.

Code and Metadata Are Governed Alike¶

Salesforce business logic is built through both code and configuration. A permission set, a validation rule, or a Flow can change the behaviour and security of an org as much as an Apex class can. Every change, code or metadata, flows through the same reviewed, tested, and audited path, and nothing is changed by hand in production.

Governance Is Proportionate to Risk¶

Not every change deserves the same scrutiny. Metadata is classified by the blast radius of an erroneous change, and the level of review follows from the classification: some metadata is prohibited from version control entirely, high-risk metadata requires elevated review, and low-risk metadata is eligible for an expedited path. The tiers and their procedures are set out in Section 6 and Appendix B.

Pragmatism, with Visible Exceptions¶

Standards are set at what can be achieved and sustained, not at an ideal. Test coverage has a floor of 85% across the org, not a target of 100%. A system-mode database operation is flagged for review, not banned. A scheduled job may be gated so that it does not run in some environments, even though code may never behave differently from one environment to the next. Exceptions are allowed, but every exception is explicit, justified, and reviewed.

Building in the Org¶

One Automation Framework¶

All automation, whether Apex triggers, Flows, or the platform's other automation tools, runs under one automation framework, with one consistent bypass structure. An extremely large org may also need a single bypass-everything permission, built into every automation including validation rules, so that data loads can run without firing automation or validation. Use it with caution: it switches off the org's safeguards for whoever holds it.

Built-In First¶

Standard components and built-in platform features come first: Lightning base components, permission sets and permission set groups, Salesforce Shield, and the platform's own classification fields. They are maintained, secured, and made accessible by Salesforce. Custom work is reserved for what the platform cannot do; nobody reinvents the wheel.

Retire Legacy Practices¶

Legacy practices are retired, not carried forward, and API versions are kept current. Keeping current is real work, because a new API version can bring significantly different default behaviour, such as stricter security enforcement, but that work is done rather than deferred.

Configuration, Not Environment Flags¶

Behaviour that must differ between orgs is set by configuration in each org, never by code that detects whether it is running in a scratch org, a sandbox, or production. Code that branches on its environment runs untested paths in production and hides behaviour from review. The reasoning is set out in full under Logging Levels by Environment.

Determinism¶

The system works as designed, every time. The same input, in the same state, gives the same result, whoever runs it and whenever it runs. A regulated industry has to show that this is so, to an auditor or a regulator, and not only believe it, and an org that behaves differently from one run to the next cannot be shown to do anything.

Determinism is the principle that Testing puts into practice: a test is the proof that a behaviour is the same each time, and Proven Functionality is the priority that demands the proof. This ensures that behaviour never depends on the environment (Configuration, Not Environment Flags), and is why the static analysis gate is built on deterministic tools, with an AI review tool as an advisory layer on top (Section 5).

Testing¶

Behaviour is proven, not assumed, and so Determinism is shown rather than hoped for. Every piece of logic that the org relies on, in code or in configuration, has an automated test that shows what it does. Anyone can run the test, at any time, and it gives the same answer.

A test that proves something has three qualities:

• It is contained. It makes the data that it needs, and it puts a stand-in in place of anything outside the unit that it tests. It does not depend on the records or the users that one org happens to hold. So it gives the same result in a scratch org, in a sandbox, and in the pipeline, and it fails for one reason only: the logic changed.
• It checks behaviour. It asserts what the logic is meant to do, for the people who really use it. A test that only runs the code proves nothing, however much of the code it covers (Proven Functionality).
• It runs with no person. The pipeline runs the tests on every change and on a schedule, so a change that breaks a behaviour is found before production, by a test and not by a user.

Tests also say what the logic is for. The next person to change it learns from the tests what it must keep doing, and learns at once when a change breaks it.

Each kind of logic has its own way to apply the principle: Apex tests for Apex, and for the declarative automation that an Apex test can reach (Apex: Testing), and Jest tests for Lightning web components (Jest).

A Shared Environment¶

Many people and many teams use the same org. What one of them builds, the others see, and often depend on. So the org is kept clean and uncluttered for all of them, and no user builds something that gets in the way of another user.

Three things follow from this:

• Not every user can create a thing that many users share, such as a dashboard or a public list view, and the name of each one says what it shows.
• Clutter is removed on a schedule. Reports saved to the Unfiled Public Reports folder are cleared out weekly, so that nobody relies on a report that was never meant to last.
• A user who needs a change asks for it in one place, with a ticket.

The A Shared Environment page explains each of these.

Inclusive for Everyone¶

The org and everything around it is built to be accessible to everyone, and to include everyone (Accessibility). Code is indented with tabs, so that each developer can set the indent width they need. Language is inclusive: "allowlist" and "denylist", never "whitelist" and "blacklist". A term that carries an implicit bias, in code or in a comment, is reported at severity 4, wherever it appears: whitelist and blacklist, master and slave, and the others on Salesforce's own list (Salesforce Updates Technical Language). Enforced by AvoidTermsWithImplicitBias.

Say Which Way, and Why¶

Salesforce often has more than one way to do the same thing. There is also often more than one way to enforce a standard.

When these standards show more than one way, they say which way is better, and they say why. The reason is usually one of three: the way works in more places, it is more exact, or it is easier to maintain. When no way is better, the standards say so, and the choice is then one of style.

These standards never show one way as if it were the only way. A reader who knows the reason can make the choice.

Rules¶

The rules that this page mentions, with each rule's standard in one line and the section that mentions it.