Tuesday, July 14, 2015

Agree on Guidelines Before Adding Code

Remember how your high school and college research papers were graded partly on niggling formatting concerns?  The point was to make sure we all used ibid, idem, op. cit. and loc. cit. correctly.  By getting us all following the same style, the teacher had an easier job understanding our work and we learned to better understand the work of others.  These are the same reason you should define code guidelines for your Salesforce org.
A good style guide provides grounding
without weighing you down.

Whether you are a Salesforce Administrator who works with vendors for your development needs or an in-house developer yourself, documenting basic code style and guidelines for your org should be considered a must.  Code guidelines help ensure that the code can be maintained for years to come and that the org is well documented down to the code level so that admins and developers alike have a thorough understanding of what takes place in the org.

A lot of Apex programmers start with the Google Java Style Guide, which is a great starting point, but you may want to create something brief to share among everyone writing code for your org.  Here are some suggestions for a brief Apex Style Guide:

Style

  1. Avoid unnecessary whitespace.  Whitespace is helpful for indicated blocks of code, using indentations at the beginnings of lines or blank lines before methods, for example.  But whitespace inside of lines of code adds to maintenance time.
  2. Use tab rather than spaces for indenting lines of code to ensure they line up properly and reduce character count.  Indent lines of code within a method by one level from the method.  Indent the code contained by a loop by one level from the line that sets up the loop, for example.
  3. Limit code to 100 columns wide, even in comments so that it can be read without scrolling.
  4. Break SOQL statements into multiple lines with new lines for each clause: From, Where, Order By, etc.  Selected fields should be listed in ascending alphabetical order.

  5.   Map<id,account> aMap = new Map<id,account>([SELECT Id,Name 
                                                  FROM Account 
                                                  LIMIT 50000]);

  6. Comments should appear at the beginning of every class and at the beginning of every method in block format (/* */).  
  7. At the beginning of each class, comments should
    • describe purpose and list related files (classes, triggers, components, VF pages, etc either called by or that will be calling this file) as well as HTTP services called, if any
    • list author name(s) and creation date
    • include modification dates and authors and purpose of modifications
    • list business processes in order they are addressed in the code as a brief summary of methods.
  8. At the beginning of each method, comments should
    • Describe purpose and detail parameters and returned values.
  9. Trigger logic should be contained in at least two files: the Trigger and the Handler(s) containing the business logic.
  10. All code should be ‘bulkified’ to avoid exceeding governor limits when multiple records are processed, at the very least, SOQL and DML statements should only appear outside of loops.

Naming Conventions

  1. File names should begin with a Primary sObject name, followed by a description of the action the code performs, followed by the type of class (eg. Controller, Extension, Helper, Utility, Test, Trigger).  For example, you might have the AccountAddressUpdate Visualforce page and the AccountAddressUpdateExtension controller extension.
  2. Avoid spaces and underscores in file, class, method and variable names.  Also avoid abbreviations when possible.  
  3. Method names begin with a lowercase verb.
  4. Classes should use camel case (eg. CamelCase) while Methods and Variables should use nerd case (eg. modifiedCamelCase).  You could have a controller extension class called AccountAddressUpdateExtension with method updateAddress and variable newStreet, as an example.
  5. Use all caps for constants such as MAXIMUM and MINIMUM.  Constants should be placed after the class header comments and before the first method and method header comments so they can be easily located and updated.
  6. Append “Test” to the class name for all test classes.  For example, the class AccountAddressUpdateExtension would have a corresponding AccountAddressUpdateExtensionTest. 
  7. Collection variables should be plural or otherwise represent the fact that they represent a collection (eg. recordMap, newAccountMap).

Deployment

  1. Remove System.debug statements before pushing code to production.
  2. Require positive and negative scenarios in unit tests using assertions that are clear. 
  3. Salesforce defines minimum code coverage as 75% but we prefer minimum code coverage of 90%.

Fundamentals

  1. For integrations, employ a 'single source of truth' model where possible—data should be stored in one location and referenced by other systems or pulled on an as needed basis only. A redundant system should be created for backup purposes, but should not be used as a data source except in the event of failure recovery. 
  2. Follow the rule of 3 and the abstraction principle. If the same code is used 3 or more times, it needs to be implemented as a reusable class, method or loop. Programmers sometimes refer to this as DRY v WET : "Don’t Repeat Yourself" vs "We Enjoy Typing"). Create abstract code for reusable procedures.