When I started my ServiceNow journey back in a chilly February of 2012, I was learning so many new things. At the time I remember trying to be super conscious of not picking up any bad habits, so I would always make special notes of things that might come and haunt me in the future.

For example, we've all heard that age old piece of advice of "comment your code". I find it fascinating that there's pros and cons to this, in that the con side is that it could impact performance - well if it's just a single line to remind you either what the function does, or what type of parameters it's expecting are, in reality it's going to be absolutely fine.

If it's an essay, then sure it might but in reality even with a 100k executions in a minute it would be so negligible that you wouldn't perceivably notice it. Therefore the pro is that in the future if you need to debug it, you can quickly catch-up to speed with what-ever the note states potentially saving you time and unnecessary troubleshooting steps.

The same is also true for single letter variables;

var a = b-c;

Best-practice over the decades of all technology implementations has taught us that variables should be meaningful, because if we (or someone else) has to come back to that bit of code in the distant future that person shouldn't need to unpick the code (no matter how skilled they are) in order to understand it's intent and thus fix it;

var RemainingFruit = Oranges - Bananas; // this is what's left in our shopping basket

So, being considerate in our code is a good thing. Everyone has to start their coding journey somewhere and no-one wants to be that person who stays until 1am on a Friday trying to unpick someone else's code where a single comment or a meaningful variable could have saved a lot of time, effort, stress and unnecessary work.

What if I said message strings were no different?

Just because we can, should we?
So let's take the idea of adding a simple info message to a form;

g_form.addInfoMessage('This is my message');

Now, lets imagine a few years later there is now a need to provide the services in another language. If there's lots of code snippets like this it would mean that:

1. We'd need to find them - no small task
2. We'd need to modify the scripts - again, no small task because it could cause feature inter-dependencies if it contradicts our development cycles.
3. Because we can't easily identify, we don't know how many message's we need to consider for translations until 1 and 2 are actioned.

So, going back to our "Scripting in ServiceNow" course and remember what our tutors would say - "it's best to call getMessage". Putting the language aspect aside for a moment, the reason is actually quite simple. If the process owner ever wants to change the wording of the message then it doesn't require changing the code. Instead, the "message" in the [sys_ui_message] record needs updating which is just data.

What does the code amendment look like?

g_form.addInfoMessage(getMessage('This is my message'));

On it's own like this it doesn't do a whole lot. It is calling the message API and it will show "This is my message" but there's still one more thing we need to do. Which is to make a record in the [sys_ui_message] table:

Key - "This is my message"Language - "en"

Message - "This is my message"

This means in the future if we want to change the text to "This might be my message", we can just update the record.When it comes to the languages aspect, and if our coding standards have been thorough enough to rigorously follow this concept since the beginning, we therefore know that all we have to do is export our custom made records in [sys_ui_message] for translation and re-import in our additional desired target language.There are some subtle nuances for different types of scripts but as general rule they follow this concept:

In that very bottom example, if we created a message record for a key of "show more", it absolutely could have a message of "this is my text" when called in the widget. This is to show and convey that the "key" is a unique entity meaning if you create it once, then it can be re-used in multiple places, saving you time, effort and potential future expense.

Wait, there's one more thing
When it comes to other languages, we need to be mindful that we also try and help the translators. Those translators (machine or humans) need some help aka context, to what they are translating:

The above is an example of a "concatenated string". This means that the sentence is made up of multiple objects within a script.

Going back to our idea of "just because we can, should we?", yes it might be easy to write and do in English sadly it does not make it equally as easy in other languages due to differences in grammar and typical sentence structure.

In the first example saying "you have" with a number followed by "items in your shopping cart" might not work. If you don't speak English as your native tongue, try translating the 3 above examples and see what it comes across as.

SummaryWhat have we learned and what's our take away? Well, when designing and building a solution, always think about the future. Think about the ease of expansion in the future, think about how someone else could troubleshoot the design or add to the design.

When I'm designing and building something I personally always ask my-self - "what would it be like for someone else looking at my code who doesn't know how to code as well as myself?" and "how easy is it to add to this?"

As usual, if you liked this, please like, share and subscribe as it always helps

Labels: