Apex to the Rescue?
Salesforce is an excellent platform for multi developer coding collaboration. Using Apex, a developer can implement features and functions that simple cannot be anticipated in a boiler plate, one size fits all solution. There are almost as many unique business rules within the Salesforce user base as there are grains of sand on the beach. This is where Apex comes into play.
With its Java like syntax and flexible object oriented capabilities, Apex allows Salesforce programmers to write a myriad of custom features and functions to meet customer needs. Apex can be used to manipulate Salesforce data, talk to other external systems using SOAP and REST and deliver endless capability to meet custom business and technical requirements.
What the Heck are These Things?
The beauty of Apex is its flexibility, the problem with Apex is its flexibility. Salesforce provides an outstanding multi-developer coding environment, where many developers can create, write and edit Apex code in one environment at the same time. Here-in lies the problem. It is more common for developers to have their own unique style than it is for developers to write with a common style. There are no automated rules in Apex to control naming conventions, code styling and structure. This lack of controlled style is a feature of Apex, like any other programming language, in that a developer can basically work off a clear canvas and has freedom to be creative. The downside is that that creativity can cause issues when developers need to revisit older code, or developers need to update or reuse each other’s code.
All too often developers will create code and not follow a command shared style that is enforced across a development team. Sadly, it’s also very common for a single developer to change their own style from one class or method to the next.
Developers often create Apex classes or triggers without a standard naming convention. For instance, one Apex class might be named “SuperZ” and another might be named “Reporter”. These names give no indication of the purpose or use of the structure or methods inside the class. This creates a significant issue when the classes actually perform specific functions and the class functions might be reused by another class.
Additionally, developers might commit the biggest sin of all code writing rules. They fail to comment their code to state the purpose of a class or an internal method. This can wreak havoc on a team development environment where code might need updates and the original developer is on vacation or unavailable for any other reason. There have been many instances where a developer must revisit code that they authored weeks or months earlier and they find themselves in a jam because they can’t even understand their own code because they neglected to write comments.
Standards to the Rescue
The good news about Apex is that a developer or a team can establish unified and consistent coding standards and styles. The style, naming convention, and structure implemented provides a base on which a developer can write code that fellow team members can quickly navigate and update.
Fortunately, there are pre-existing standards which can be used as a foundation for creating a custom team or organization wide Apex coding standard. Google, Sun and other organizations publish and maintain a set of standards that can be refined to meet a specific team’s needs so that code is readily comprehended and updated by the author and other team members.
Google’s java style guide {https://google.github.io/styleguide/javaguide.html} can be used as a foundation for class names, declarations, formatting, commenting and other stylist elements. Admittedly, Google’s style guide may have some standards that would not apply to Apex, however there is a robust foundation for coding standards that can be easily adopted by a developer, team or organization.
Basic Coding Guidelines
Here are some basic coding guidelines that can be applied to virtually any Apex Class or Trigger
If no other standard were adopted by a team, inline comments are the single most important facet of coding guidelines. Commenting code should be treated more like a COMMANDMENT than a guideline. It goes without saying that all other elements of style and even functionality are secondary to writing inline comments. Back in the ancient days of programming, developers would start with pseudocode before they wrote their first line of code. While writing pseudocode has become less the norm of today, writing inline comments is an absolute requirement. Inline comments create the foundation of any class, trigger, internal method or function.
Inline comments help a developer frame their thoughts
Inline comments help a developer define the intent of their code
Inline comments provide a hand rail to ensure that they are writing clean code
Inline comments provide a roadmap for other developers
Inline comments make it easier to maintain and update code
Adopting a Javadoc standard for comments is an excellent start for creating solid inline comments. A Javadoc comment can be exported using automated tools so that coding structure across many classes and triggers can be printed to create a map of features without having to open a class or trigger to see what’s inside.
Inline comments can be inserted into existing code without affecting functionality and should be created where no comments exist. This can be done whenever comments do not exist and will not alter the functionality of existing code.
Fortunately, there are existing tools for automating the process of creating inline comments. There are comment tools built into the Eclipse IDE and a plugin for MavensMate which can create the basic comment structure with one or two key strokes.
Formatting
Formatting is the second part of writing code that has no impact on functionality, but it has high value in creating easily read code. Using proper indents, braces and white space can make existing poorly formatted code much easier to read, update and comment.
Teams and organizations should agree on formatting structure. There are is some flexibility to how braces and white spaces are treated. A team should make quick decisions on their format and run with it. Automated tools are available to quickly restructure code if it is determined that a formatting change is required.
Applying formatting changes to existing code should be the first step in documenting poorly standardized code, and it makes commenting easier. However, good formatting is no substitute for proper inline comments.
Naming Conventions
Naming conventions are a part of code styling that may affect existing code functionality. This is due to the fact that class names, trigger names, internal class names, internal methods, internal functions and internal variables may have their names changed to meet an enforced coding standard. As such, much care should be taken when implementing a new naming convention.
Naming conventions are taste defined guideline that may differ from one organization to the next. However, once a naming convention has been established it MUST be implemented and enforced.
General Google Naming Conventions:
Class names are written in UpperCamelCase. Class names are typically nouns or noun phrases.
Method names are written in lowerCamelCase. Method names are typically verbs or verb phrases. For example, sendMessage
Constant names use CONSTANT_CASE: all uppercase letters, with words separated by underscores.
Non-constant field names (static or otherwise) are written in lowerCamelCase.
Parameter names are written in lowerCamelCase
Local variable names are written in lowerCamelCase
Make the names of various items mean something beyond a generic phrase. This will help a developer and their teammates understand what the class, trigger or method is doing and its purpose. For instance, “WebInterface” is a poor name, whereas “WalmartWebService” lets someone know that the class provides an interface to a Walmart provided web service.
Write Code Worthy of Your Name
In the end, start with the beginning. Write code from the start that you will associate with your name. A good developer will create a class comment that states the purpose of a class or trigger, and have an author comment with their name. Be proud of the work you deliver and associate your name with it.
Once coding standards have been created and their enforcement applied to a code base, teams will become more efficient and flexible. It will be easier for developers to switch and share responsibilities because everyone is writing code which easy to read, comprehend, maintain and update. Adopting and enforcing coding standards will minimize those 2am calls because another developer needs an update to a class they don’t normally maintain. That first developer will be more able to make a change themselves because they can understand what a class or method it doing.
Lastly, for organizations, they should understand that functional code is a minimal requirement. Messy code that gets turned over to another organization could significantly damage the reputation of the last authors and their organization.
Comparison
Note the two code block below. Functionally they do the same thing. However, the first code block uses comments to explain the purpose of the Product Discounts class and the applyDiscount method. It also uses indents and naming conventions to effectively communicate its purpose.
The second block uses no comment, poor naming conventions and formatting making it much harder to maintain.
The minimal effort to adopt and utilize coding standards can head of problems before they start.
