Anyone who writes code thinks that it is self-documenting. I’ve heard many developers (including myself) say “Just read it, it’s obvious.” Well, that can be true when you are in the thick of a project, and the business requirements driving the need for the code are fresh in your mind. Unfortunately, we are all very busy, trying our best to make changes as fast and efficiently as we can, so even those with the best intentions never go back and add those elusive comments that truly drive home the details.
Then, to exacerbate the issue, Dynamics CRM (both Dynamics CRM 2011 and Dynamics CRM 2013) has us “hook up” events in ways that make it difficult to get a big picture of all the code that can exist on a form.
With that in mind, let me share 6 best practices that I’ve adopted that have helped get my client-side code that much closer to being self-documenting. (I saved the best one for last… so make sure you read them all!)
To take this one step further, I also encourage you to use the same name for the file and the web resource. If the file is named “Account_main.js”, then your web resource should be “prefix_Account_main.js”. Unfortunately, I’ve seen cases where this has not happened, and I had a hard time finding the code that needed modification.
Best Practice #2: Don’t modify script directly in the web resource text window
We’ve all done it, but if you are not careful, it can be easy to forget to get those changes checked back into source control. This practice also lets me edit the code in a friendlier editor (like Visual Studio). My editing process typically looks like this:
Following this practice makes it easy to see all relevant code for any given form in one place. This is really the first step to making that code a little more self-documenting. If there are separate forms, there is likely separate business logic. When multiple forms have the same logic… see the next best practice.
Best Practice #4: Put functionality required by multiple forms into utility files
This is probably the most obvious best practice. Make sure the functionality is separated into files logically so that only relevant script is getting loaded onto the forms. This does make self-documenting code harder, but this is where creating a comment is necessary. If there is a call to a function from another web resource, make sure to add a comment. The code block below calls two functions from the LeftNavtCount.js file:
| // Requires LeftNavCount.js
Best Practice #5: Create a new function for each triggered event
For every entry point into the client-side code, create a single function. For example, the requirements for when a form loads, are as follows:
- Set the contract field to require if the case type is set to “Contract Dispute”.
- Filter the contract lookup based on the value in the account field.
Now let’s say that I have a function defined to do both of those things:
| function setFieldRequirementLevel()
// Get the value for Case Type then set the requirement level for Contract
This is what SHOULD NOT BE DONE:
Instead, structure the code like this, and then register just the form_OnLoad function:
| function form_OnLoad()
Now, when I need to know what happens when the form is loaded, I can open up the source file. I don’t have to look at the source file AND the form’s Event Handler.
Best Practice #6: Register all events in the form OnLoad
This is probably my absolute favorite best practice. In the previous paragraph, I showed how making sure all the code for a single event is all called from one function. This practice takes things one step further and makes it so that the only Event Handler that has to be configured is the form OnLoad event.
In the scenario we used above, we also want to call setFieldRequirementLevel when Case Type changes, and we want to call filterContractByAccount when Account changes.
Let’s make two new functions:
| function CaseType_OnChange()
Now for the final event… register the OnChange events:
| function form_OnLoad()
NOTE: The OnSave event can be registered OnLoad as well.
Now that we’ve done this, when I need to change any functionality on the form, all I have to do is change the .js file, upload it to the web resource and go. Even if I add a new on change event… no more opening the form designer for code changes!!!
Follow these best practices when creating client side code, and you should get that much closer to code that is self-documenting!
What best practices do you use when documenting and creating client-side code? Leave your comments and thoughts below. Have more questions on best practices for Dynamics CRM? Email us at firstname.lastname@example.org.