This chapter is intentionally different. With the potential exception of the last chapter, I've tried to maintain a tone of discussion rather than prescription. This chapter, in contrast, is intentionally prescriptive, more so than the last. This is how I build applications and write code on the Salesforce1 platform. The techniques and tips described here have been developed and used in both small and massive orgs. This is intended as an in-depth look at some overarching best practices of architecture—how we structure applications—and engineering—how we code applications. Specifically, we are going to focus on:
- Keeping our applications and code simple
- Testing meaningful things well
- Naming things intuitively
- Auto-documenting our code
- Writing maintainable code
Of all the things I've learned about software development, the single most important one is to keep things simple. It's often technologically fun to craft more complex solutions, especially when learning new technology stacks. I promise, however, the more complex the solution, the harder it is to debug when it fails. Because code is only one option for creating logic on the platform, maintaining simplicity not only means keeping code simple, but also not using code unless we need to. Knowing where to look for implemented logic can be anything but simple. The solution, however, is as maddeningly simple as it is difficult—always develop declaratively, falling back to code only as a last resort. Application developers cannot just be code-warriors, but instead must be knowledgeable and comfortable with the vast array of declarative tools provided by Salesforce. Additionally, we must keep up with the new improvements and features each of the yearly releases bring three times a year. To be clear, I don't mean to imply that we should refactor vast amounts of existing code into process builder processes or visual workflows. That's just not practical. However, when a feature such as process builder is released, we should embrace and use that feature rather than writing more code. Code, however, is where we can have the clearest, cleanest impact by keeping things simple.
Chanting the mantra keep it simple doesn't automatically make our code simple. As time goes on, our code inevitably, it seems, gets more complex. Furthermore, because no two orgs share the same complex business requirements, no two orgs are complex in the same way. While it's possible to derive and state guidelines for complexity, they've always felt too nebulous to act on. I've found it's more meaningful to set goals for more tangible things than complexity. For instance, one classic measure of complexity is the Cyclomatic complexity metric, essentially a count of the logical paths a method contains. Traditionally, Cyclomatic complexity is calculated by one of a family of algorithms as part of a static code analysis. Tools such as SonarQube, Checkstyle, and findBugs can inspect code for its Cyclomatic complexity after it's written. Some editors, such as IDEA's Intelli-j, even offer in-editor calculation of such metrics. Sadly, all these are Java-focused, and while they work, they often don't understand Apex-specific changes to the general Java language. Apex's use of List, Set, and Map data structures, for instance, tend to confuse Java static analysis tools. Just because these tools do not operate perfectly in Apex doesn't mean we have to abandon them or the ideas that underpin them. In fact, while not as automatic as static analysis tools, we have another way of inspecting complexity at a quantifiable level: code reviews. With that in mind, let's identify some quantifiable marks of complexity. These are written in the form of questions to be asked during code review. They are, by design, controversial and aspirational. If followed through, they will result in simpler, more maintainable code.