Code Standards¶

A practical set of standards for Salesforce code, with the static analysis rules that enforce them. Testing and enforcement expectations live within each page rather than as separate topics. Each standard applies the Principles, and each comes with its rule wherever a rule can enforce it, because every rule has a standard, and every standard has a rule where one is possible.

• General: the standards for every language: accessibility (text alternatives for images, and names for buttons and links, in every kind of markup), documentation (comments), and naming, by language
• Apex: governor limits, readability, documentation, complexity and unused code, error prevention, the API version, sharing and access mode, security, hard-coded values, testing, asynchronous Apex, exception handling, and architecture
• HTML and Visualforce: accessibility, comments, Visualforce, CSS, SLDS 2, and XML
• JavaScript: security, the API version, readability, duplicated code, error prevention, linting, and testing, for JavaScript wherever it runs
• Lightning Web Components and Aura: Lightning Web Components before Aura, Lightning Web Security, and Aura
• Testing: the standards for the tests of Salesforce code, whatever the language

Where more than one engine can make a check, all may be included here. In those cases, there may be a suggestion on which may safely be deactivated. However, if two rules each find overlapping but not identical violations, both rules should remain active.

Standards and reasons that hold for every language on these pages. A language page says what the standard is for its language. This page says why the section exists.

The Structure of a Language Page¶

Each language has the same sections, so that a developer knows where to look and a reviewer knows what to expect.

• Readability holds the standards that make code easy for the next person to read.
• Naming, beside Readability, links to the language's part of General: Naming, where the naming standards of every language are.
• Code Style, inside Readability, holds the stylistic choices: standards that may not change what the code does.
• Formatting, inside Code Style, holds the purely cosmetic standards that Prettier applies, such as bracket spacing.
• Required Formatting, inside Readability, holds the formatting that the platform requires.
• Error Prevention holds the code choices that work today and could cause a problem later.

Readability¶

All code is readable and documented (Readability). Code is written once, and it is read every time it is reviewed, debugged, audited, or changed, often by someone who did not write it. Three things follow.

• A reviewer can approve only what they can follow. Readable code is also what makes every other standard reviewable.
• A developer who did not build the code, and an auditor, can review it, audit it, and change it safely when it explains itself.
• A change is safe only as far as the person who makes it understands what it touches.

Readability is the aim. Naming, formatting, braces, documentation, and limits on complexity are the means, and each language page states them.

Code Style¶

Code style is the set of stylistic choices that make code easier to read and that may not change what it does: where a bracket goes, how a name is cased, whether a list ends with a comma. When every file makes the same choices, a reader sees what is different, a reviewer looks at the logic and not at the layout, and a diff shows a change of meaning and not a change of layout. A tool makes this easy: Prettier applies the formatting, and a rule reports what it did not apply (Prettier).

Code style matters less, or not at all, in four cases.

• A tool settles it. Prettier decides, so nobody argues and nobody formats by hand. The standard is the setting of the tool.
• Either choice reads as well as the other. These standards then take no position, and each organisation decides. The indentation of CSS is an example.
• It would change what the code does. A style choice never outranks a standard that affects behaviour. A choice that is more than style belongs under Required Formatting or Error Prevention, not under Code Style.
• It makes the code harder to read. Readability is the aim and style is a means. A style rule that works against the aim is the wrong rule.

Required Formatting¶

Required formatting is formatting that the platform requires, as against formatting that these standards choose. A developer has no choice, so there is nothing to decide. The standard makes sure that a tool applies it and that a rule reports where it was not applied. An example is the trailing comma in an Aura component: Salesforce prohibits one after the last item of an object literal or an array literal (Aura: Required Formatting).

Error Prevention¶

Error prevention covers code choices that work today and could cause a problem later. They are not about how the code looks. A comparison that converts its operands, or a switch statement with no branch for a value that nobody expected (Switch Statements), runs correctly until the day it meets the case that nobody wrote. A standard here asks for the choice that fails loudly and early, and not quietly and late.

Documentation¶

The code says what it does, and documentation says what the code is for and why it is written that way. The standards for documentation and comments apply to every language, and they are on General: Documentation.

Anti-Patterns¶

An anti-pattern is a common way of writing code that looks reasonable and causes a problem. These cut across languages. Each links to the standard that deals with it where there is one.

• A race condition. The result depends on which of two operations runs first. In Apex, a query with FOR UPDATE locks the records it returns, and another transaction that tries to update a locked record waits up to 10 seconds and then fails with an exception. Without the lock, a transaction that holds an old copy of a record can overwrite changes made in the meantime; locking the record first returns a fresh copy (Locking Statements).
• A hard-coded value. A credential, a record ID, a URL, or an IP address written into the code works in one org and breaks in the next (Hard-Coded Values, Credentials in Markup).
• Copied and pasted code. A fix made in one copy is missed in the others (Duplicated Code, Duplicated Markup).
• Work in a loop. A query, a DML statement, or a describe call inside a loop runs once for every item and reaches a limit on a large set (Bulkification).
• A swallowed error. A catch block that does nothing hides the failure from everyone who needs to know of it.
• Dead code. Code that nothing calls still has to be read, and it can be mistaken for code that runs (Complexity and Unused Code).

Standards Not Adopted¶

Some standards that were researched are left out of these recommendations on purpose. Throughout these pages, sections titled Standards Not Adopted list some of them. Most are not anti-patterns: their benefits are outweighed by the cost of a policy that is too restrictive, or by work that gains less developer time or platform speed than it costs. A researched rule or standard is listed where it contradicts an adopted standard, or where enforcing it would have unintended consequences.

Not every standard that was left out is listed. Only those that merit an explanation are, because they are popular, or because enforcing them could lower developer productivity or work against one or more of the Principles.