Good software is intuitive enough that people can create or modify data as needed without having to understand what’s going on “under the hood”. This allows business users to spend less time trying to figure out a bunch of technical details about the applications they’re using and more time working on growing their organizations to better serve their constituents. This seems obvious, but there’s actually a lot that goes into building really good software. If your organization doesn’t have proper guidelines in place for developers to follow when they’re working on your IT systems, providing that seamless experience will be next to impossible. And things can get even worse over time.
Once an application has been built, it needs to be maintained, and the developers responsible for doing the maintenance may not be the same developers who wrote the initial code. In order to prevent your applications from becoming unsustainable nightmares that don’t actually serve the needs of your users, you need to make sure that certain practices are followed consistently. This is where standards come into play.
There are always a multitude of ways to solve any problem and all developers have their own methods for writing code based on their previous experiences. Every approach has its own merits, and establishing a set of standards isn’t necessarily saying that one set of development methods is better than another. It’s simply a way to make sure that all developers who work on your applications are following a consistent set of processes. Without standards, every developer who works on an application will follow what they consider to be best practices. If their definition doesn’t match the previous developers’ definitions, the end result will be inconsistent code that’s likely to lead to things like:
So how do you decide what standards to put in place to make your organization successful? And how do you keep them up to date and ensure that they’re enforced? There’s no single right or wrong answer. You’re not necessarily looking for perfection as much as simply providing a way to make sure that any developers who work on your applications are aligned on the way their code should be written. So while the decisions around which specific standards you put in place are up to you, our team does have a good set of recommendations around the approach you can take to get there.
Developers have a reputation for liking things in a specific way. Although it is just a generalization, this process should be collaborative. Bring a mix of architects, development managers, front and backend developers, and QA resources on multiple levels to divide and conquer the work based on the members expertise.
A good mixture of roles and expertise results in higher quality work. Since everyone focuses on what they really know, each section has multiple eyes and perspectives. A good example of this collaboration is having managers and architects that typically review code contribute, and also the developers that still write code everyday and tend to be more up to date on latest developments and gotchas contribute.
This distributed ownership also results in higher adoption and buy-in since developers are more likely to adhere to standards if they are not imposed from the top. It also helps divide the work which is helpful since there usually aren’t a lot of resources available to work on initiatives like this.
If your organization has multiple Salesforce instances, make sure to include stakeholders from as many as possible. In an environment with a mature governance framework including an architectural committee and change board, this group ultimately owns the standards and their enforcement. Although the group should play an active part of developing them, it is recommended to also include other members as mentioned above.
Putting together development standards can be a daunting task as well as a never ending one. Your goal shouldn't be to create a manual on how to write code. To prevent yourself from falling into the trap of “Analysis-Paralysis”, try to avoid the urge to keep adding more rules and edge cases and don’t allow unresolved questions or issues to become blockers to publishing an initial version.
Instead, try to think of your development standards as a living document which can be enhanced and modified as needed. Put together an initial version of the document based on the basics and the issues you observe most often and release it. Then gather the committee regularly to review and update the standards as necessary.
A recommended methodology to developing development standards is to approach them like a project. You can even use source control tools to track changes, versions and enhancements you want to address. Then, a couple of times a year, you can gather the committee to review the changes and release a new version.
You don’t have to start from scratch when writing your development standards. Although there are bound to be some nuances that are specific to your organization and implementation, there are a lot of general best practices and resources that you can use as a starting point. Each programming language has different go-to resources that you can use to start, for example:
These resources are just examples and your development standards committee should research further and consolidate multiple sources to ensure high quality standards.
It's extremely important that you make your development standards work for your organization. There are going to be areas that are specific to your implementation (e.g. naming conventions, patterns or frameworks used) and some of the general rules may not align with how your team or architecture is structured. Use existing resources to help you get started and don’t be afraid to customize them.
Nobody likes to read through long dry documentation. Development standards are a technical document and should definitely be precise, but try to make them readable and easy to follow as well. Most importantly, make sure the information they contain is easy to find. Development standards should be a reference guide and not a monolithic document that is read once and forgotten.
Follow the recommendations below when writing them:
After writing your standards you need to release them, but you shouldn’t rush to get them out the door without proper planning. There are three main considerations to rolling out development standards.
Leverage your committee to conduct the training. Having a committee that is spread across the organization ensures that each group of developers will have close contacts who were involved in the effort to create the development standards. This helps to ensure that training and change management process flow more smoothly. Make the committee members known, have them conduct walk-throughs of the standards and enforcement tools and provide office hours for discussions and Q&A.
Give Developer managers flexibility around how to roll out the standards to their teams. Different teams can have different paces, deliverables and experience levels that may require different approaches or timelines. Having a small pilot team that can test the enforcement tools and how developers interpret the standards can be beneficial for large organizations but delays the process.
Most of us are starting with an already built implementation and codebase. Refactoring it to adapt to a new set of development standards can be a time consuming task that is often not easy to justify and that can be a deterrent to implement them. Set the expectation that the new standards apply only for new and changed codebases and do not require going back and refactoring everything.
If possible, leverage the automated tools to run an analysis of the existing codebase and allocate part of each release to solving high priority violations.
It’s important to keep standards consistent as technology evolves to avoid having them become stale and unusable. As part of the iterative nature of building development standards, your committee should meet a couple of times per year to discuss changes and enhancements.
In particular there are 2 things to pay attention to:
Salesforce has 3 major releases per year. Each release introduces new classes and functionality that can change the way your developers should code on the platform. Sometimes these are relatively small changes like the introduction of the APEX Switch Statement in the Summer 18 release. Other changes, such as the introduction of Lightning Web Components (LWC) carry a much higher impact and may require their own set of standards.
Your codebase will also change over time. As it does, you may have to change the way you build upon it. These changes can range from something as simple as updating your naming conventions to complex efforts like adopting new technologies or frameworks. For example, if you decided to adopt TDTM as your trigger framework, your coding standards should change to reflect the steps to build triggers in Salesforce using that framework.
For each of these languages, development standards should be a set of rules that describe how to develop consistently across your organization. Standards are not intended to be a manual on how to code, which would become challenging to maintain and overly complex. However, they should be comprehensive to ensure consistent, high quality code. Achieving that balance can be complex and different organizations may choose different approaches around how detailed, formalized, and consistent they want to be. The size and expertise of your team as well as the culture of your organization will play a role as well.
Regardless of your approach, you’ll find that many of your sections share some commonality with other coding standards. Some are programming language specific and don’t depend on the implementation while others will be very specific to your organization. It is outside of the scope of this paper to provide a set of development standards but the sections below can help you get a sense on what to include and how to organize them:
This section is fundamental to ensure the code is not vulnerable. It highlights standards related with ensuring proper access to functionality and data as well as preventing hacks. Examples in Apex include:
Most of these are common to all implementations and the Apex PMD ruleset has a nice collection of them but your organization go a step further or define exceptions.
The goal for this section is to ensure that code is not overly complex and is readable, reusable and maintainable. It can include standards like:
In this section, it is common for your committee to discuss the specific thresholds for each standard. For example, what should be the max size of a class?
The goal for this section is to ensure code runs efficiently. This includes standards like:
This section includes general best practices to make the code more readable like:
These standards can be very thorough depending on the formality of your organization. Some of them may seem cosmetic, but they are fundamental to ensuring that your code can be accurately read, reviewed and debugged with a minimal number of errors. Their enforcement can also be automated very easily.
This section can be divided into multiple sub-sections. It has more impact on your development standards than any other section and includes the rules on how to develop in your organization beyond instruction level details.
This section can include general best practices like:
More importantly, the guidelines in this section can also instruct on how to use patterns and frameworks that your organization defines as standards and wants implemented across all the applications. These are very organization specific but examples in Apex include (among others):
Patterns to be implemented depend highly on how complex and customized your Salesforce applications are. The above are just a few examples observed in some Enterprise orgs and do not intend to be prescriptive. Your organization will need to define which frameworks and patterns to adopt as an architectural decision independent from writing the development standards, but which should definitely be reflected to ensure consistent and correct adoption.
Naming conventions are a fundamental and often overlooked part of development standards. They ensure the ease of locating related functionality associated with a specific feature and help developers navigate a Salesforce implementation containing multiple applications and business units. Within code, they mostly apply to class or component names, but this section can extend to configuration elements too. If you’re looking for a starting point to develop this section, check out the naming conventions for the Salesforce services team.
Some of the conventions are common practice like appending “Batch” to batch classes, “Test” to unit test classes or “Ctrl” to controller classes. Some can be specific to your organization like prefixing the application name in all metadata (when a namespace is not used) or the name of a specific framework (e.g. TDTM) in all the classes leveraging it.
Naming conventions is frequently something that spreads across multiple sections of the development standards and it’s not its own self contained section since it is part of styling, patterns, testing, and others.
It is outside of the scope of this section to outline the full testing/QA process part of your development methodology. It's goal is to standardize on how to unit test within Salesforce code, in particular how to write unit tests and what to test.
Standards around how to write unit tests include:
Standards around what to test typically include:
It’s important to ensure that your testing goes beyond simply testing backend code. Salesforce enforces 75% code coverage in Apex code but it is fundamental to address unit testing of front end code as well as automated testing scripts for both code and configuration.
The goal of this section is not to define how to document a specific application but rather how to document within your code. There are some general best practices but this will be very specific to your organization.
Technical governance defines how you enforce your standards as part of your Software Development Lifecycle (SDLC). Enforcing standards helps make code more maintainable, more readable, and more understandable by the technical team. These benefits can be realized with very little effort by automating the process using modern tools, and a hands-on approach can build a stronger team as well as better code.
The basic SDLC for Salesforce customer orgs makes use of multiple sandboxes in a stepwise sequence of testing leading up to deployment to production. This sequence usually begins with automated unit tests in a Developer sandbox followed by a combination of unit and more end-to-end automated integration tests in a Developer Pro sandbox. The last step typically includes capturing user feedback for immediate bug fixes and next phase development stories in a Partial or Full sandbox with replicas of user data. While testing standards are usually enforced at each step, code standards are often enforced at the earliest environment change.
Salesforce Developer Experience Command-Line Interface (SFDX CLI) helps automate these steps as part of your Continuous Integration / Continuous Development (CI/CD) process. With the CLI, you can build a CI/CD process that includes automation verifying fundamental code and test standards are upheld before code can be automatically moved from one environment to the next as part of your SDLC.
Code scanners work a bit like a word processor’s grammar check function, they automatically flag code that does not meet predefined standards. Tools usually have a default set of rules based on syntax, which can be checked by linters and more complex static code analysis tools that inspect for potential security breaches like Cross Site Scripting or SOQL injection.
Popular tools for the Salesforce platform have default standards based on documented best practices and security. Some tools can also be customized according to your internally defined code standards. For example, Salesforce offers an open source ESLint tool for LWC that can be customized to meet your needs.
For more complex static code analysis, tools range from free and open source to paid options. Free tools include a CheckMarx scan offered by Salesforce security for 360,000 lines of code in your org each year (at the time of this writing), as well as the Apex PMD scanner, which is an open source project that includes a command line interface for use with your CI/CD. The CheckMarx free scans include a detailed report that rates issues and recommends fixes based on platform best practices. PMD scans, on the other hand, can be customized to run against any subset of Apex rules for a more customized report. Since both are free, we suggest you give both a try.
Paid tools include CodeScan.io, which provides a rich experience for enforcing development standards, and a paid CheckMarx product that removes the limitations of the free option.
Note that automated code scanners may not have the full and complete picture of your code during the scan. For example, if you handle SOQL Injection security via a standard and reusable custom class and method, the scanner may not understand how security is being handled and may return a false negative result. Similarly, if you have Apex code to bypass sharing and run in system context, it could be flagged as a security concern and you may see a recommendation to use “with sharing” that would go against your business requirement.
You may have classes that operate without sharing because they are meant to do something in system context and bypass security as part of the business requirements. The scanner may not understand your business requirements and return false results. False negatives are also helpful, by flagging and documenting exceptions you improve your code reliability and maintainability.
Your SDLC should include backing up code to a shared repository such as GitHub, GitHub Enterprise, or similar tools from other vendors as well. Tools like these not only back up your code and configuration metadata, they also offer a raft of other features as well. For example, a developer can request a code review right in the tool where another developer can look at highlighted changes to the codebase and verify that the changes make sense to accomplish what was needed and uphold your standards.
Even though it is a time-consuming and manual process, code reviews offer even more benefits for understandable code. In a code review, an experienced developer reads code and offers constructive feedback to improve the code based on internal standards as well as knowledge of platform and organizational best practices.
Manual code reviews can also be run like a technical handoff where one team member shares the design decisions and technical details of a solution with another team member who can request improvements. These can also be run between two teams working in the same Salesforce org.
The maintainability benefits of manually reviewing code make it worthwhile to spend time ensuring that the experience is uplifting and positive for developers, something they look forward to and agree is beneficial for all. In order to reach code review nirvana, set rules of engagement for all manual code reviews and establish what the intent is:
Rules of engagement should also establish a timeframe so that code is not held up by reviewers. In addition, you can define when changes are complex enough to require a demo and walkthrough of the solution, which can be incorporated into sprint review in mature Agile workplaces.
Not all code changes are that complicated. Sometimes, a well understood section of code can be refactored to take advantage of platform improvements or to be made more reusable. In these situations, there may not be a need for a demo and developers can use a shared repository to get insight into changes and review them online with written feedback for a quick turnaround.
Whether feedback is offered in person or in writing, rules of engagement clarify what the reviewer should prioritize investigating and how to communicate changes that must be made vs changes that could be made. Some reviews uncover security or performance issues that prevent code from moving to the next environment and can be noted with keywords to call out the requirements. There may be high impact suggestions like refactoring to make code more reusable.
Other reviews may only find more stylistic considerations to improve readability that could be fixed in a future refactor rather than holding up a project. For the latter, consider using “POP” to denote “Point of Polish” feedback. For the former, high impact suggestions, consider “HI” as a shorthand way to note “High Impact” feedback.
Good governance with carefully planned use of automated tools and well curated feedback improves your CI/CD process, fosters growth and teamwork, and enables developers to provide even better products for end users. As enforcing standards and communicating becomes a habit for your development teams, time-to-delivery and release errors both should decline. And the number of developers with skills and knowledge to improve code should increase.
|SDLC Step||Tool / Technique||Description||CI/CD Support|
|At every step||Automated unit testing||Apex and UX automated testing should meet standards and may be part of Test Driven Development strategy||Tests can be evaluated automatically in many CI/CD processes using SFDX commands.|
|Before moving from a Developer sandbox||Automated code scan||Scanning programmatically for common pitfalls||May include CLI for use with most CI/CD processes or may offer other support of CI/CD|
|Before moving from a Developer sandbox||Manual code review||Reading and offering constructive feedback and knowledge transfer||Manual updates in the shared repository can trigger automated processes|
|Before moving from an integration sandbox||Automated end-to-end testing||Apex and UX automated testing should meet standards and support business domain||Tests can be evaluated automatically in many CI/CD processes using SFDX commands.|
|Before moving from User Testing or the training sandbox||Manual testing||Hands-on testing and training with end users||Manual|
Ensuring that external teams also adhere to your standards can be a challenge, but you can mitigate potential problems by setting expectations up front. Find partners you trust and have a discussion about your coding and testing standards before beginning any projects. Make sure your partner knows what standards you are holding them to, and let them know if there is any room to negotiate on the standards you have given them. Also, make sure you have someone available to them who can help them meet the standards more easily by answering their questions, prioritizing needs, and regularly reviewing their work.
You may be hiring a partner because there isn’t anyone in-house with both developer skills and time. If that’s your situation, finding a partner you trust is most important. Ask to see what sort of hand-off documentation they provide and what sort of technical enablement they provide. Consider hiring an independent architect or technical program manager (TPM) to help review the work for security and best practices and ensure it meets the scope of requirements. This should be someone who can help you understand the skills needed and the skills offered by developers working on your project.
The best possible outcome is a great partner who not only helps to solve the business problems you’re trying to solve but also helps you to understand how the code they’ve written interacts with the platform to meet your needs. It’s a two-way relationship that benefits from regular interactions. Consider Agile methodology and regular sprint reviews to demonstrate work, followed with a technical review to discuss fitness and maintainability of the new functionality and to outline the technical approach chosen.
Lastly, expect your partners to do their own Quality Assurance (QA) and then do your own rigorous QA as well. Encourage users to log into sandboxes and feel free to go off script as they actively try to break things. It’s a sandbox, if something can be broken, that’s where you want it to break, not in your production org. Use their test results to determine whether you want documentation and training to address shortcomings or if your release date might need to be postponed to ensure that defects have been resolved. Ideally, you won’t find yourself delaying, but if it ever does get to that point, always remember that your users will accept a delayed rollout a lot more readily than they’ll accept a broken system.
Creating a good work environment for developers, both internal and external, should offer opportunities for creativity and growth. Creating clear guidelines by establishing standards frees developers up to focus on creating optimal solutions rather than consternating over small concerns. In addition, providing guidance and teamwork for developers to support each other’s best efforts improves the work that all developers will be able to produce.
Good technical governance and a well defined SDLC can help developers understand and adhere to the standards. Involving business stakeholders as well can build the relationships between product creators and product users to ensure better results for both groups. While introducing new standards and processes may appear to slow down development work initially, as the team gets more practice with these, you should see both development and maintenance become less costly in the long run.
Tiago Ruivo is a Senior Principal Customer Success Architect at Salesforce.org. He has a deep technical background and ample Salesforce implementation experience, as a customer, partner, and inside Salesforce, helping organizations of all sizes. As a Technical Architect and a Delivery Director, Tiago was responsible for writing multiple Development and Coding Standards.
Bonny Hinners is currently a Principal Customer Success Architect at Salesforce.org, a social impact center of Salesforce focused on partnering with the global community to tackle the world’s biggest problems. Bonny's work has spanned from a Fortune 10 company with multiple orgs to small 10 license nonprofits. She is also a speaker at Salesforce and community events and a volunteer with RAD Women, closing the tech gender gap by mentoring women who want to learn to code on the Salesforce platform.