TIL Thursday: NetSuite Coding Styles Explained

Have you ever wondered why the reference SuiteCommerce Advanced modules are written the way they are?

Within in any development team decisions have to be made regarding the style, conventions and standards that the team will adopt for their code. When I first started learning the SCA code, I had some questions and so I caught up with Sebastian Gurin, Senior Software Engineer at NetSuite, who is part of the team that chose the coding styles used in the SuiteCommerce Advanced code.

One of the most characteristic choices you have made is with the define statements in the RequireJS modules. Almost everything is on a new line.

Yes. We came up with four concepts for this:

  1. Very short syntax, where everything is on one line.
  2. Short syntax, where define, the module name, the array of dependencies, and the function are all on separate lines.
  3. Long syntax, like short syntax but additional line breaks are added when a comma is used.
  4. Flexible syntax, where formatting depends on the amount of depencies. If there are very few, use the very short syntax, if there are many then use the long syntax.

Well it looks like you went with the long syntax.

It helped us counteract a very common problem. When declaring a module with a lot of depdencies, name and variable mismatches become more likely. By putting everything on one line it becomes a lot easier to see. We also decided to add in a separation between the classes, templates and libraries (and to always put them in that order). Finally, doing it this way means that there should be no horizontal scrolling when verifying dependecy names and variables, which is a pain.

On the subject of breaking JavaScript onto new lines for commas, why comma-first JavaScript?

This could be a long discussion. There are some justifications for using this style...

Like making it easier to spot mistakes, cleaner diffs in version control, being easier to scan...

But there is no particular reason why NetSuite use it. The decision to use this style was made a while ago and for coherence we kept it in the SCA modules. It is an unorthodox style, and some developers are unfamiliar with it, so that can be a negative. Ultimately, though, there is no requirement for customers to do it this way.

I also noticed that all SCA modules contain 'use strict'. Why was this adopted?

There are plenty of good reasons to use it. I think there are two crucial factors:

  1. We like the consequences of 'use strict'. For example, if we try to initialize an undefined name then we will get an error. It forces us to write better, more secure code.
  2. We have to support several runtimes, not only in shoppers' browsers but also the NetSuite environments that run the serverside JavaScript. Doing this gives us greater certainty about the outcomes of our code.

Sounds like good advice for third-party developers, then. Why did we adopt Backbone?

We started developing this solution a few years ago and back then it was the most, and probably the only, mature framework available. Other now popular frameworks, like Angular, just didn't exist. Backbone is very lightweight, and we like that.

We previously used Underscore for templating but the newer versions of SCA uses Handlebars. Why the switch?

Personally, I think Underscore is very good for templating as it gives us a lot of control over what goes into the templates. But this was a problem for our customers when it came to the portability and creation of their own customizations. Underscore templates naturally contain a lot of visual logic which was very easy for more HTML-focused developers to break, and to write customizations that would break when the product was updated.

Changing the way we used Underscore could help mitigate this problem (for example by introducing the idea of template context) but it wouldn't prevent its users from adding their own logic to the template and make them hard to maintain.

And so you adopted logicless templating.

Exactly. Handlebars really reinforces the idea of keeping logic outside of the templates. Having a clear separation helps compartmentalize the different parts of rendering the final webpage. If the template context is rich and well-documented, it's a lot easier for more HTML-focused developers to make their changes.

Finally, why do Sass files have to start with an underscore?

This is part of the extension to the Sass @import rule, specifically what are called 'partials'. Putting an underscore in front of the Sass file's name prevents it from generating a separate CSS file with that name. Remember that we want to compile Sass into one CSS file per application and this is how we do that.

Further Reading