The purpose of this document is to describe best practices and standards that will be used when developing and deploying ServiceNOW solutions. This document will serve as a set of guiding principles, with the goal of developing software with a common set of core methodologies and techniques that will aid in the development of robust and maintainable software. This document will supplement other coding “best practices” that have been generally agreed upon in the industry, including the documentation provided by ServiceNOW (see > http://wiki.servicenow.com/index.php?title=Coding_Best_Practices#gsc.tab=0). Examples are used to demonstrate principles, examples given in RED are examples of how NOT to do something.
An important guiding principle will be self documenting code. The ideal state is a code base that is so complete, so understandable, than anyone with a base understanding of the technologies will have complete functional understanding of the software. Practically speaking, this is not achievable but should be the ultimate goal. This document will help outline principles to approach this state.
I. Comments
Comments should be added to code when: the
1. They add information that can not be provided by the code.
Header comments are strongly encouraged, and should describe the overall function as well as where it is called from, associated workflows etc…
2. They clarify complex code.
If the coder feels the need to comment code due to it’s complexity, first the code should be re-examined to evaluate whether or not it can be
written in a more easy to understand manner. There are times, despite best efforts, where this is not possible and comments should be added
to explain the code.
3. They are used as a supplement to code indentation
For all but trivial conditional blocks of code, comment the end blocks. For example:
if (count > N) {
….
….
} //end if count > N
4. They are used as markers, to tell the developer that something might need to be changed, or that something should be changed.
We will use the comment “FIXME” to describe any piece of code that we need to come back to at some future point in time. Use all caps to facilitate
searching.
Comments should not substitute for poorly written code. In the following two examples, a properly named variable takes the place of a comment as is the preferred solution:
var useThisCategory = ’12345’; //This is the ServiceDesk category
var serviceDeskCategory = ’12345’;
Comments that do not provide additional information should be avoided. Commenting simply to comment is harmful to code readability and gives the false impression that we “doing the right thing”. For example:
x++; // increment x
II. Hardcoded Data Constants
Hardcoded data constants should stored in a variable, named such that they are understandable and accurately describe what it represents. Javascript objects can be used very effectively to provide good information. For example:
var CONST = {
groups: {
computer_security = ‘12345’,
servicenow_support = ‘23456’
}
tasks: {
incident: ‘23456678’,
change: ‘34567788’
}
states: {
open: 22,
in_progress: 23,
cancelled: 24,
closed: 25
}
}
The above object allows precisely describes the constant – for example CONST.states.cancelled will precisely describe that it is a constant representing a STATE named cancelled.
Simpler constructs could be used where appropriate, such as:
var computer_security_group = ‘12345’;
var open_state = 22;
III. Use brackets {} on all if/else clauses.
All if/else clauses will use {}. For example
if (doThis)
thenDoIt();
if (doThis) {
thenDoIt();
}
IV. DRY – DO NOT REPEAT YOURSELF
For all but trivial pieces of code, use functions. If you find yourself wanting to cut and paste a piece of code, stop and think about turning this into a general function. Use libraries (a.k.a script includes). If your implementation spans several places, then use a common ScriptInclude for all related activities.