Monday, April 25, 2011

[Salesforce.com] The Code Review Tool Kit

Today I want to share a set of shell scripts that I am using when working on my code reviews.

Code review, the big picture
It consists in performing a validation of the work done by a partner, checking:
- technical design,
- code quality, respect of the best practices,
- governor limits,
- etc.

Context
Too often, I do not have an Internet access on the customer site. I am retrieving the Salesforce organization meta data using eclipse and my 3G key; then I am working off line.

What do the scripts?
On the first hand, the scripts provide a high level overview of the code structure: how many classes, pages, components, triggers, where are the classes used, etc. On the other hand two additional tools: find every usage in the org of a field and get all the relationships between the objects (lookup and master/detail).
All the scripts generate a CSV output for an easy integration in Excel, copy/paste from the shell to Excel! (I like this motto)
This is really save my time and let me focus on the review analysis.

Script sources
The code is available under the GPL license 3.0

apex.sh
Where my class is used?
Generate a CSV text output that provides an overview of each class usage.
Rows: class
Cols: pages, components, triggers

vf.sh
On which classes and components does my page rely on?
Generate a CSV text output that provides the list of classes, components and objects (standard controller) used by each page.
Rows: page
Cols: standard controller, controller, extensions

trigger.sh
Which classes are called by my trigger?
Generate a CSV text output that provides the list of classes used by each trigger.
Rows: trigger
Cols: classes

component.sh
On which classes does my component rely on? Which pages include my component?
Generate a CSV text output that provides an overview of classes used by each component, and also the pages that are using this component.
Rows: component
Cols: controller, extensions, pages

field_usage.sh
Where is my field used?
Generate a CSV text output that provides the list of meta data where the provided field is used.

objects_dep.sh
What are the relationships between my objects?
Generate a CSV text output that provides every relationship (lookup/master detail) pointing to another object.


SOLUTION DISCUSSION
The requirements
My scripts could be replaced by a program that communicates with the API and uses the DescribeObject method. But just keep in mind my two requirements:
- an off line usage
- Keep It Simple

Why a shell script?
The scripts might be optimized, or would be nicer written in a language such as Perl or Ruby rather than a shell script. I experimented several Perl XML parsers but they were slow and required Perl and Unix skills to be compiled, too complex to be shared. The choice of shell scripts appears as the best solution, with an easy deployment regardless the platform:
- Unix or gnu/Linux shell
- Mac OSX shell
- Windows using Cygwin
Awk is also required (provided with these environments).
My working place is gnu/Linux, Ubuntu flavor.

Fill the spaces!
Nature abhors a vacuum. I recommend not using blank spaces in your Eclipse project names. Always prefer an underscore. This is really making sense when it comes to shell scripts. In a shell, all space characters contained in file or directory names should be protected with a backslash:
$ cd Force.com\ IDE
Same issue in a for loop: e.g. the string “Force.com IDE” is processed as two separate files/directories:
$ for i in `echo "Force.com IDE"`; do echo $i; done
Force.com
IDE
The solution is creating symbolic links:
olivier@Ubuntu1:~/Workspaces$ ln -s Force.com\ IDE Force.com_IDE

olivier@Ubuntu1:~/Workspaces$ ls -l
total 4
drwxr-xr-x 21 olivier olivier 4096 2011-03-05 09:55 Force.com IDE
lrwxrwxrwx 1 olivier olivier 13 2011-01-26 10:43 Force.com_IDE -> Force.com IDE

Remark 1: my Eclipse workspaces path is ~/Workspaces
All my projects are located under “~/Workspaces/Force.com_IDE”

Remark 2: the provided scripts will work even if your files/directories names contains spaces because I protected the paths with double quotes.


Preparing the environment
Unzip the archive scripts.tgz and copy the scripts to your “Force.com_IDE” directory, that is where are located your projects directories. This is convenient, the scripts will be able to reach any of your eclipse projects.
To run the scripts, you have to download at least the following meta data:
- classes
- pages
- triggers
- components
- objects
Remark: all the meta data are required for the script field_usage.sh.
To add more meta data to your existing Eclipse project: open the project properties window:
click on the “Add/Remove” button:
choose your meta data:

Code naming convention
I am working with this naming convention:
Visual force pages: VF + [number] + [name].
Triggers: [object name] + [event] + [name]. The name is optional
Apex classes (trigger): AP + [number] + name
Apex classes (controller): VF + [number] + name + _Ctrl. The class name should match with the Visual force page name
Apex classes (others): name
Components: CO + [number] + [name].
Remark: the number are defined in your technical design document (assuming you have one).


Scripts “limitation”
The best approach would had been to work with a code parser, a XML parser and multi lines regular expressions. I choose a “quick & dirty” way, using simple shell commands line:
Pro's
- quicker development
- easy to understand, maintain
- very fast script execution
con's
- hell, no con's, that doing the job pretty well!


THE SCRIPTS
./apex.sh
Run the command:
apex.sh [Directory]
Result:
The script prints to the standard output a CSV text result. Each row represents a class and provides the list of the pages, components and triggers where the class is used:
When the class is used in several vf pages, the names are separated by a pipe sign.

Here is a command line sample, where Dummy_Org is the name of my Salesforce organization.
olivier@Ubuntu1:~/Workspaces/Force.com_IDE$ ./apex.sh Dummy_Org
class,page,component,trigger
AP01_OpportunityStatus,,,OpportunityAfterUpdate
AP02_AccountHierarchy,,,AccountBeforeCreateUpdate
AP03_OpportunityLost,,,OpportunityAfterUpdate
CO01_mashup_Ctrl,,CO01_mashup,
VF01_AccountNew_Ctrl,VF01_AccountNew,,
VF02_ContractWizard_Ctrl,VF02_ContractWizard,,
VF03_AccountList,VF03_AccountList,,

You might wish to copy/paste the result to Excel and get a fancy layout:

vf.sh
Run the command:
./vf.sh [Directory]
Result:
The script prints to the standard output a CSV text result. Each row represents a visual Force page and provides the list of the Object controller, Apex controller, Apex extension used by the page.

Here is a command line sample:
olivier@Ubuntu1:~/Workspaces/Force.com_IDE$ ./vf.sh Dummy_Org
page,stdcontroller,controller,extensions
VF01_AccountNew,,VF01_AccountNew_Ctrl,
VF02_ContractWizard,,VF02_ContractWizard_Ctrl,
VF03_AccountList,Account,,VF03_AccountList


trigger.sh
Run the command:
./trigger.sh [Directory]
Result:
The script prints to the standard output a CSV text result. Each row represents a trigger and provides the list of the Apex classes used by the trigger:

Here is a command line sample:
olivier@Ubuntu1:~/Workspaces/Force.com_IDE$ ./trigger.sh Dummy_Org
trigger,classes
AccountBeforeCreateUpdate,AP02_AccountHierarchy
OpportunityAfterUpdate,AP01_OpportunityStatus|AP03_OpportunityLost

In this example, the trigger OpportunityAfterUpdate is calling two classes: AP01_OpportunityStatus and AP03_OpportunityLost


components.sh
Run the command:
./components.sh [Directory]
Result:
The script prints to the standard output a CSV text result. Each row represents a component and provides the list of the Apex controller, Apex extension used by the component and the visual force pages where the component is used.

Here is a command line sample:
olivier@Ubuntu1:~/Workspaces/Force.com_IDE$ ./components.sh Dummy_Org
component,controller,extension,page
CO01_mashup,CO01_mashup_Ctrl,,


field_usage.sh
Run the command:
./field_usage.sh [Directory] [field name]
Result:
The script prints to the standard output a CSV text result. Each row represents a meta object where the search field is present.
Columns: object type, object name, number of matches.

Here is a command line sample:
olivier@Ubuntu1:~/Workspaces/Force.com_IDE$ ./field_usage.sh Dummy_Org Segmentation__c
metaObject,name,occurence
applications,Dummy_Org_App,1
classes,VF01_AccountNew_Ctrl,10
classes,VF02_ContractWizard_Ctrl,8
layouts,Account-Customer Layout,1
layouts,Account-Prospect Layout,1
objects,Account,3
objects,Site__c,7
profiles,Account Manager,11
profiles,Admin,12
profiles,ContractManager,11
profiles,MarketingProfile,11
profiles,ReadOnly,11
profiles,Standard,11
triggers,AccountBeforeCreateUpdate,1

Remark 1: as the search relies only on the name, the script will return every occurrence of the file name. E.g. if you have created one custom field “segmentation__c” on the account object and another one on the opportunity object, all the occurrences will be returned, regardless their parent object.

Remark 2: I do not remove the comments in the Apex and Visual force (this will come in a future release). So when the field name appears in a comment it is considered as a valuable match.


objects_dep.sh
Run the command:
./objects_dep.sh [Directory]
Result:
The script prints to the standard output a CSV text result. Each row represents a relationship.
Columns: object 1, type of relationship, object 2.
object 1 as a relationship pointing to object 2.
the type of relationship might be “lookup” for a lookup, and “md” for a master-detail.

Here is a command line sample:
olivier@Ubuntu1:~/Workspaces/Force.com_IDE$ ./objects_dep.sh Dummy_Org
parent,relationship,child
Account,lookup,AccountExecutive__c
Account,lookup,CountryId__c
Contact,lookup,CountryId__c
Town__c,md,CountryId__c


Conclusion
I hope you will find these scripts useful. I am using them almost every day, so I will bring improvements and will post updated versions to this blog. Feel free to give your feedback by dropping a note in the blog comments.

3 comments:

  1. Love the scripts! Thanks for sharing!

    ReplyDelete
  2. Download links are throwing 404 page not found

    ReplyDelete
  3. Could you please provide sources? I am in need of something exactly like you have described here.

    ReplyDelete