This series focuses on improving coding style. It will not add any "cool" or "tight" functionalities you've never heard of. Its sole purpose is to improve 3 things: Readability, Maintainability and Expandability of code.

The first part of this series will focus on abbreviations.

Abbreviations

Abbreviations are awesome. They take up less space, save time while coding and are mostly easy to understand. They have been a thing while coding since the beginning and many have grown up coding with them (at least i have). So how come, something so well used, can be considered "bad".

Readability.

Let's look at some code. What does this line of code do?

gr.setValue('short_description', gr1.short_description);

Pretty simple right. It sets the short description of something to the short description of another thing.

Lets compare that to this:

newChildTask.setValue('short_description', incident.short_description);

Ok. Does the same thing. But we can actually tell, that this time it has to do with some kind of childTask getting created, probably from within an incident, but most definetly in relation to one. Now we got a lot of information without any business requirement, concept or context.

Lets add some context:

var gr1 = new GlideRecord('incident');
if(!gr1.get(this.sysID))
  return;

var gr = new GlideRecord('incident_task');
gr.initialize();
gr.setValue('short_description', gr1.short_description);
gr.setValue('parent', this.sysID);
return gr.insert();

Pretty simple right? This piece of code will set the short_description of a new incident_task to match the incidents one and make the incident the parent. Finally it will return the sys_id. Beautiful. Now what's the issue with this line of code?

Well let's make it readable:

var incident = new GlideRecord('incident');
if(!incident.get(this.incidentID))
    return;

var newChildTask = new GlideRecord('incident_task');
newChildTask.initialize();

newChildTask.setValue('short_description', incident.short_description);
newChildTask.setValue('parent', this.incidentID);
var newChildTaskID = newChildTask.insert();

return newChildTaskID;

Looks almost the same. Now, this goes back to what we have started with. We can read and understand both code pieces. But the first one only allows that, because of the given context.

Let's blur the context and add some examples:

gr.setValue('short_description', gr1.short_description);

newChildTask.setValue('short_description', incident.short_description);
requestItem.setValue('short_description', catalogItem.short_description);
changeTask.setValue('short_description', changeRequest.short_description);
historyEntry.setValue('short_description', agreement.short_description);

Where as the first line of code does not change at all, what does it actually do? Without knowing the context this can be quite challenging to guess. What if these operations were spread apart? Sure, the context must be somewhere, but you would have to search for it.

Going through a particular part of a script, would always leave the question, what this line does:

gr.setValue('short_description', gr1.short_description);

Sure, going through the rest of the script, looking for the definition of "gr" and "gr1", would give the answer out of the context.

But it costs time that could've been spend fixing the issue. So:

To maintain code, readablitity is king. Quit using abbreviations. Please.