It’s been a while since I’ve posted something. You’d think I would’ve had time to post a thing or two during vacation, or on the weekends. But sadly for me, vacation meant “home improvement project” and weekends mean “chore catch-up time.” Apparently, blogging time takes a backseat to those things.
If you don’t know what NodeJS is, visit their website. Install it. Read about it. Play around with it some. Go ahead, I’ll wait right here.
Are we back? Great, let’s continue.
If you don’t know what JSDoc is, visit their website. Read about it. Once again, I’ll wait.
Ok, moving on.
One more time. If you don’t know what JSHint is, read about it.
Great. Now, to stuff I actually did…
Putting it all Together
How does it work? First, install node, ensure it’s on your classpath. Next, clone my repo. Finally, open a command prompt and navigate to the directory where you cloned the repo. Run “npm install” to install all the dependencies for the project. Once it’s run, you can use the command “gulp” to run the program. There are other commands you can use individually as well:
gulp extract – Will extract the script files from your instance
(The rest assume you’ve already run gulp extract – or just gulp – at least once.)
gulp jsdoc – Creates jsdoc for script files
gulp markdown-server – Creates markdown for just server side code
gulp markdown-client – Creates markdown for just client side code
gulp markdown-all – Creates markdown for all of the code
gulp jshint-server – Runs JSHint on server code
gulp jshint-client – Runs JSHint on client code
Note, you may wish to configure your setup differently. I have mine just extracting UI Scripts and Script Includes, because that’s where a majority of my code really lives. (My Client Scripts and Business Rules typically call whatever classes they need from the respective files.) The only thing I added to the jshintrc configuration file were the globals ServiceNow has of GlideSystem (gs), GlideForm (g_form), and GlideUser (g_user). You may wish to modify the file to be less strict (or even more strict). The way to do that is shown in the JSHint documentation.
Why Would I Need This?
Well, why wouldn’t you? By using this tool we’re effectively agreeing to:
- Document all code properly
- Ensure we’re writing code properly, which is more important than the first item on the list
That doesn’t seem too unreasonable. The benefits of doing this are:
- An easier time finding defective code
- Less chance to repeat writing a function you wrote a long time ago (you have HTML or markdown docs now that you can search through!)
- Hopefully, fewer defects
Troubles and Issues
The main trouble is that ServiceNow’s own code is NOT JSDoced and won’t pass strict JSHinting. Trust me, I’ve tried. JSHint just quit after 30 seconds for too many errors. Does this mean ServiceNow is awful and needs to be re-written? Probably not. It works, but I’d personally like to be able to extract ALL the code in the system so I can get a full picture of what’s happening in my instance. I also think this would help me understand what’s happening behind the scenes a lot easier. The ServiceNow wiki (and developer’s site API documentation) is good, but there are a lot of things missing. Ever go into your console in Chrome and see what objects are available? Take a look, it’s interesting.
Since deactivating all the OOB scripts, copying them, and JSDocing and editing them for JSHint passing would take a great deal of time and effort (that may not actually be worth it), for now it’ll just have to be left out.
Where to Go From Here
Ideally, I’d have this run in a Jenkins build that I can call from ServiceNow whenever I close an update set, or at the end of the day, or even every time I update a script. This opens to the door to actual version control (just edit the .gitignore file in the repository to achieve this). I’m going to work on doing this next for my own code.
My goal in doing all of these utilities is to have the cleanest code possible. If you haven’t read Clean Code, click on the link and buy a copy. Make sure to order it via Prime so it shows up ASAP. Read it. Read it again. Apply it. Read it again in a few months. As the author says, it takes practice and time to make those principles an every day reality in your work. I’d like to think I’m getting there with having test coverage so I know I can refactor code when I need to and not worry about it breaking, as well as having tools like this documentation tool that force me to keep it clean…or else.
I’ll keep working on this project as I have the time to do so. I’ll also adapt it to extract the classes generated by my Selenium utilities update set from my second post in this series, to make test automation that much easier to get started.