Tag Archives: best practices

ServiceNow Coding Style Guide Part 1

I thought I would kick of this new blog with a topic that is very important to me,  Coding Style in ServiceNow.  Here I will present a short list of rules and principles to guide your coding.

Following this guide will make your code more readable which will make maintaining the code much easier.  That means less time trying to decipher your or co-workers code and lower costs to maintain code.  This is true of any code base but especially in ServiceNow where the developer ecosystem is so varied.

The end goal is to have all code appear to be written by a single person.

Once a good track record can be established on following these practices then you can start to introduce higher level concepts and principles.  More on those in future articles.

Personally, I disagree with long style guides and best practices documents.  If there are too many rules to start it is impractical for new developers to follow them all.  My approach is to start with the fundamentals.  Once they are mastered then you can layer in more advanced practices.  So for now I am keeping the list short. (It should fit on an index card)

Naming
Functions should be named like verbNoun, using camel case. This will make it easier to remember as well as forcing the function to perform a specific purpose.

Variables should not have abbreviations, ever.  It is preferable to use camel case when creating variables although underscores have started to be used instead.  It does increase readability but most existing code will not follow this.

Classes should always be camel case with the first initial capitalized.

Constants should be all upper case.

All record names should follow a convention.  I prefer Prefix – Script Name, where the prefix is the company name or application name.  This is applicable only where the record name is not the script name such as on Business Rules and Client Scripts.

Script Includes should follow the same convention as classes.  UI Scripts should be all lower case using underscores to separate words.

Formatting
There are two options for brackets, same line or not.  I prefer same line.  As long as you are consistent it is a matter of opinion

Whitespace should be used liberally to increase readability.  I favor using spaces within parentheses.  Line breaks to separate blocks of code within functions and two line breaks between functions.

Edit:  I am going to post this in a new article but I have started not to do this.  Instead I am following the standard of putting spaces outside of the parens.  Which seems just as readable.

Indentation should be 2 or 4 spaces but be consistent.

Semicolons should always be used.

Commenting
By all means, if you feel your code is to complicated use comments to clarify, but before you do that ask, “Can I rewrite this to make it clearer?”  If the answer is yes, rewrite the section and see if the comment is still necessary.  The goal is for the code to document itself.

Odds and Ends
Always use === instead of == to compare values.  This will prevent accidental coercion of variables.

Try and use ‘ instead of ”

Avoid ternary operators

Avoid eval

Principles
Don’t Repeat Yourself.  If you find yourself writing the same code over and over generalize it and move it to a separate function.

Never just copy and paste code.  Always rewrite it and try to understand line by line what it’s doing.  While it’s tempting to just inject a bunch of functionality, that is not going to help if there is an error or you need to modify the code.

Try to keep your code separated by intention.  For instance don’t have a single function that does a database call and then immediately updates the UI.  This is called Separation of Concerns and is the basis for other more specific principles like MVC.  Separated code will make it easier to update and reuse.

Finally, care about your craft.  Your code will likely never hang in a museum but the functionality that you are building matters to your users and it should matter to you as well.

Bonus Cheat Sheet!

Cheat Sheet
Coding Style Guide Part 1 Cheat Sheet