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.
I have written on a number of best practices, and somehow this one fell through the cracks. So here goes: A short list of bad ways to comment and why, along with the good ways of commenting your code. Interestingly this seems to be a very abundant problem in the platform and in custom code.
End of Statement Comments
This is a very "old-school" way of programming that existed back when one-, two-, and three-letter variable names were okay (btw, that was never). You know, back when we all programmed assembler? Anyway, it still pops up in script. I actually look for it as a finding when I do code reviews. So, why is this bad? It makes the code ridiculously hard to maintain; as you have to change the comments usually with the slightest change of the code. Also, it makes the code hard to read. If you like this form of commenting you have to be from the school of thought that says: "If it is hard to write, it needs to be hard to read!" This is a bad practice. Don't do it! Comments should be few and should talk about the functionality that may be hard to understand. Variable and function names should be self-documenting (see: Community Code Snippets: Variable and Function Naming).
Bad Practice:
// check for number of attachments
if (numAttachments == 0) {
...
} else {
...
} // if (numAttachments == 0)
Best Practice:
// If there are no attachments then there is problem that needs to be remediated
if (numAttachments == 0) {
...
} else {
...
}
Also remember that with the new editor if you highlight the first part of the statement it will highlight all other parts of that statement:
End of Line Comments
I consider this to be the most insulting commenting technique that exists. Well, next to explaining the obvious function of a block of code with a comment. That is commenting at the end of a line of code exactly what the code is doing. Yeah, okay, it is a toss-up. Both are equally insulting.
For example:
Bad Practice:
var userInfo2 = ''; // initialize userInfo2
g_form.setValue(‘email’,arrres[0]); //Display "email"
g_form.setValue(‘phone_number’,arrres[1]); //Display "Phone"
That first one wants to make me cry (in frustration). So the developer thinks all other developers are idiots. Got it.
Best Practice:
var userInfo2 = '';
g_form.setValue(‘email’,arrres[0]);
g_form.setValue(‘phone_number’,arrres[1]);
To borrow from a saying by Elon Musk: "The best comment is no comment." Actually, that isn't exactly what he said, but I swear it is close!
Commented Out Code Snippets
Do NOT leave commented out code in your scripts! It ends up having two nasty side-affects. 1) The code gets shipped to production like that, and if there is a bug it can make it hard to find. 2) Some poor maintenance coder comes along and not understanding it uncomments it to fix the hard to find bug. And, it makes for yet another noisy commenting practice! This example is from "real" code I found in a production instance:
Bad Practice:
function onSubmit() {
sidCartItem = g_form.getValue(‘item_guid’);
//alert(‘sidCartItem = ‘ + sidCartItem);
/*if(reqType == ‘Modify existing group members’)
Mgr = g_form.getValue(‘group_to_be_modified’);*/
if(reqType == ‘Modify existing group details’)
Mgr = g_form.getValue(‘modify_group_details’);
Best Practice:
function onSubmit() {
sidCartItem = g_form.getValue(‘item_guid’);
if(reqType == ‘Modify existing group details’)
Mgr = g_form.getValue(‘modify_group_details’);
Failing to Remove Template Comments
Another thing that I find a lot is where a coder fails to remove the OOB template comment in Business Rules, Client Scripts, or wherever! This is a known LAZY PROGRAMMER problem. Please, don't be a lazy programmer. Please. Did you know that every code review, code scanner, etc. scans for lazy programmer problems like these? They can be confusing to a maintenance programmer, they can end up part-way down in a given block of code. Do not do this. Be mindful. Clean up the mess that a template leaves.
Bad Practice:
function onLoad() {
//Type appropriate comment here, and begin script below
// Begin working through the object to locate the exact match
var tester = g_scractchpad(...
Best Practice:
function onLoad() {
// Begin working through the object to locate the exact match
var tester = g_scractchpad(...
I can't emphasize enough that good development practices are good engineering practices. You want you code to be in the best shape possible. You want your code to be a work of art! Take the proper time to make it so.
Enjoy!
Steven Bell.
If you find this article helps you, don't forget to log in and mark it as "Helpful"!
1 Comment
