NOTE: MY POSTINGS REFLECT MY OWN VIEWS AND DO NOT NECESSARILY REPRESENT THE VIEWS OF MY EMPLOYER, ACCENTURE.
DIFFICULTY LEVEL: BEGINNER
Assumes a good beginner level of knowledge and/or familiarity with Scripting in ServiceNow.
Coming from a formal Computer Science and engineering background it is sometimes painful to see certain naming conventions utilized. For example: One-, two-, or three letter variable names.
There is an old school-of-programming thought: If it was hard to write it ought to be hard to read!
I have never believed in that adage!
Did you know there were several very good JavaScript naming conventions already in use? JavaScript has been around for quite awhile (link). And, standards for the language as well (link). Most large JavaScript development shops use Java coding conventions for their JavaScript standards. A significant number of people have created a coding standard in one form or another. The best I have found to-date are:
from the document: JavaScript Guide
Air BnB Naming Conventions <- my favorite
Douglas Crockford in his book "Javascript: The Good Parts" uses single letter variables all over the place. I do not support this convention (However, in his defense he "might" be doing it for brevity in the book. 🤔).
ServiceNow supports meaningful names for variables and functions:
Coding Best Practices: Use Descriptive Variable and Function Names<- scroll down to this; it is a way into the page
So here are my thoughts on this topic:
Well named variables can:
- Reduce the amount of comments needed - self-documenting code
- Improve maintainability by making the code intuitively readable
- Reduce defects by accidentally re-using variables (gr is a prime example)
- Make refactoring of code (recognition of patterns and code footprint reduction) simpler to detect and implement
I am sure there are ones I have missed.
Name your variables and functions something meaningful. var gr is not meaningful, nor is it descriptive enough. Consider using naming conventions that define what's stored or will be stored in the variable.
NOTE: the variable name "gr" is quite commonly used to represent GlideRecord throughout the codebase. This is a bad practice even though it is in the platform! Did you know that ServiceNow's instance scan ignores their code, and has a finding on anyone using this in custom code? Try to avoid using this convention as it is not descriptive of what is actually happening. Consider, would you name an integer: var int = 5; ?
You get the idea. Something meaningful. Don't do naming like any of these:
var gr = new GlideRecord('incident');
var il = []; //incident list
var m = {};
function x(y) {...}
Each of these can be hard to maintain (even with comments)! I mean, seriously...what does the function name "x" signify?
The one exception I make to this is on so-called throw-away variables such as are used in loops. For example:
for (var i=0; i < incidentList.length; i++) {
gs.print(incidentList[i].value);
}
The function of such a throw-away variable is obvious, and making it longer may add to confusion rather than helping with readability. BTW, I once knew a company architect that insisted that such variables not be used, and forced every coder to use "meaningful" names for counters. I am of the opinion that this school of thought is tedious and unproductive (not to mention making the code hard to read and maintain - I mean: come on!). I am almost on the hate level with things like this:
for (var incidentListCount=0; incidentListCount < incidentList.length; incidentListCount++) {
gs.print(incidentList[incidentListCount].value);
}
Yuck (a professional term I use for meaning: yuck!).
Also, stay away from non-descriptive naming of variables and functions such as these:
var myObj = {};
function myFunction(things) {...}
Such names don't really state what the variable or function is for!
It is okay, and preferable, to use long descriptive names. This is known in some developer circles as self-documenting code. Look at these examples and you will see what I mean:
var incidentRecords = new GlideRecord('incident');
var incidentList = []; // list of incident objects
var incident = {};
var incident_results = new getIncidentResults();
function calculateAssetValue(assetToEvaluate) {...}
Camelcase is fine, as is Snakecase (underscores). Both are considered standards in the ServiceNow platform codebase. This kind of naming is very maintainable, and will reduce the amount of comments needed. As you can see, adding an extra (short) comment next to the variable declaration can be useful in some cases.
Don't go crazy with this though! While long names are fine, overly long names are ridiculous and can actually contribute to maintenance issues by introducing unreadability!
var thisReally_long_variableNameIsNotAGoodIdea = 5;
var iWouldNotRecommendTooLongVariableNames += thisReally_long_variableNameIsNotAGoodIdea;
var myArray = goGetAnIncidentListAndVerifyItTurnItIntoAnArrayAndReturnIt(iWouldNotRecommendTooLongVariableNames);
You get the idea, and yes, I have seen stuff like this in the codebase out there! 😝
Another thing I would suggest avoiding are two variables or functions that are named similarly. You are asking for errors to be introduced later if a maintenance coder uses the wrong one!
var incidentList = [];
var incidentsList = [];
And yeah, seen that a lot as well!
So in conclusion consider using sensible names for your variables and functions. Something descriptive, longer than four characters, and that to some degree self-documents. This improves readability, maintainability, and documentation of the code.
Enjoy!
Steven Bell.
If you find this article helps you, don't forget to log in and mark it as "Helpful"!
Originally published on: 10-22-2015 07:07 AM
I updated the code and brought the article into alignment with my new formatting standard.
3 Comments
