Organizing Script Includes in ServiceNow | Share the Wealth

[@ChuckTomasi]

Great stuff. I take exception to comments in your script includes, as someone who has had to use someone else's code, comments at the beginning defining purpose, inputs and outputs is often the only "documentation" you get. Ideally, it should be self-documenting, but I've found that's rarely the case so I give my future self and others a helping hand.

[@davidarbour9549]

You're right Chuck, self-documenting (or ideally-written) code is very rare, but it is what I always strive for. I should say that well built code should not need many comments. In practice, if I come to a point where I feel the next dev will need a better understanding of the code, I try to break that out into a new function. When that's not possible or practical, I will add a comment. What I take the most issue with when it comes to comments is when the comments don't add any value to the code.

[@ChuckTomasi]

@@davidarbour9549 Thanks David. More recently, I find myself writing polymorphic functions (e.g. a parameter can be a GlideRecord or sys_id. A little clarification in situations like this goes a long way.)

[@davidarbour9549]

@@ChuckTomasi Yeah, that's one case where documentation is absolutely critical! Speaking of, if I had a wishlist for JavaScript features, I think overloaded functions would be at the top of my list.

[@ProfessorTimbo]

Re: refactoring -- Get an IDE like Webstorm, and SHIFT+F6 to safe-refactor and code-search! It's fantastically useful. There's even a checkbox for "refactor comments" as well.

[@davidarbour9549]

I'm a VS Code junkie, but I am intrigued by Webstorm.

[@JohnCaruso]

Just wanted to mention that when you use this method of script include organization (i.e., a function that returns an object and does not use `this` or `prototype`, also known as a Factory Function), then you don't need to use the `new` operator. E.g., var service = GlideService('my_table'); // works fine

[@davidarbour9549]

Yes, but not using 'new' just looks weird to me. I guess it's just habit at this point.

[@Motorcyclemelee]

How do you unit test your script include’s private functions?

[@davidarbour9549]

I don't unit test the private functions. If a public function fails, there's a limited number of places I will have to look to figure out what's going on because I keep functions very small and focused. The private functions in this video were built for demonstration purposes. In practice, I don't use private functions very often because I can typically break those functions out into one or more other script includes.