Script with style. Readable code is a few rules & conventions away.
Table of Contents
- Naming Convention
- Alignment and Indentation
- Debatable Styles
- Sum Up
First things first: this Salesforce Marketing Cloud SSJS style guide is highly subjective. You may use it as it is, implement only some parts of it, or ignore it altogether. There are only two rules that I believe are a must-have:
- Be consistent across your codebase.
- Strive for good readability.
Everything else is preference. And you are just about to learn about mine.
SSJS gives you a lot of freedom when it comes to naming and letter case. But instead of going freestyle with that flexibility, we should leverage it to build something meaningful and readable. I decided to focus also on simplicity.
Use descriptive names to provide context.
As John F. Woods said,
always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Meaningful and consistent names are an excellent starting point for living a long (coding) life with a limited amount of frustration and regret when someone asks you about your year-old code to adapt to a new project.
Applying the rules listed below is easy when you write the code and remember its logic but can be a challenge after resetting your memory by writing few other scripts. Make your SSJS better with meaningful variable and function names.
- Use descriptive variable names. It is better to have a long explicit one (
isTrackingSuppressed) than a short mysterious abbreviation (
- When the variable is a boolean, prefix it with
aredepending on the underlying data).
- When the variable is a date, suffix it with
- When the variable is an array, use a plural name (
- Use descriptive function names. It is better to have a long explicit one (
getEmailAddress) than a short mysterious abbreviation (
geteml). Think how you can add as much information as possible, without adding unnecessary bits (
- Use a verb (
send) as the first part of the name to tell what the function is doing.
- Apply variable naming rules to the parameters - leave single-letter names for minifiers.
camelCase for all elements of JS syntax.
var only), functions (no array goodies), and methods.
For all of those I'm using
camelCase. It's the most popular convetion, so it will make it easier to work with other programmers, leverage code snippets and onboard new-to-SSJS people to SFMC development.
You Should Know
name are two different variables that can have different values, so it's critically important to have a stable convention.
PascalCase for all elements of SSJS syntax.
I take a different approach when working with SSJS Functions from both Platform and Core libraries. For any element coming from those, I use
Sparse is better than dense.
Readability counts. Having fewer lines is not worth the mental gymnastics required to read a condensed code. It is also much easier to find unclosed brackets.
You Should Know
I have two exceptions to this rule - both related to
if statement shorthands.
- Ternary operator
Ternary simplifies basic
else statements, and when used correctly, it should be readable in a single line. If you fear it might be hard to understand, you probably shouldn't use the ternary operator in the first place.
- Single line
Similarly to ternary, single-line if statements also should be used only for basic
if statements. Whenever there is any complexity (be it
else statement or just a longer case body), I always go with the expanded syntax.
It's up to you to decide how complex is too complex. Whenever in doubt - use expanded syntax.
Use indentation to highlight code relationships.
This rule extends the expanded syntax guide. Don't stop at expanding. Indent. It will help you quickly understand the relationships between the code lines.
The easy way to implement correct identation is to add a level whenever you open curly bracket and remove one whenever you close it. However, sometimes readability can be improved with even more identation, for example within expanded array.
You Should Know
It's safer to use spaces instead of tabs for indentation. And it's more readable to use four spaces instead of two. You can configure your code editor to output four spaces on each Tab click.
Use spaces wherever it makes the code more readable.
To visually separate elements, use spaces:
- Around operators.
- Before opening curly bracket and after closing curly bracket.
- After commas.
- After keywords (
To provide important context, don't add spaces:
- After opening and before closing non-curly brackets.
- Between function name and arguments.
Apart from letter case and indentation, some additional style rules are important to consider. Multiple arguments favour various conventions, so feel free not to follow my recommendation as long as you stay consistent across your code.
Add a semicolon after each statement.
If you do not use semicolons, JS will add them for you using Automatic Semicolon Injection (ASI). In most cases, it works perfectly, but there might be some situations where the outcome is not what you expected. And that will lead to a very long and frustrating debugging session. If you want to think about ASI when writing, you may ignore semicolons.
If you don't want to worry about ASI, per JS language specification, you should:
- Mark the end of your simple statements with a semicolon
;. Think variable declarations and operations.
- Don't end complex statements with a semicolon. Think
- But... you need a semicolon after the
whileloop when considering the statement blocks). Oh, and you will need to add them in your
forloop iteration rules.
That's also a bit to digest and worry about when writing the code. Let's simplify it.
While you don't need a semicolon after complex statements, it won't hurt. It can even help you if you plan to minify the code. So, to make it straightforward and fail-safe, I recommend adding it after each statement.
Use single quote style.
With SSJS, you can use either single quotes (
') or double quotes (
"). Don't follow the random approach of Salesforce SSJS documentation - choose one and be consistent.
I prefer single quotes for SSJS:
- I frequently use string variables with HTML that uses double quotes. Using single quotes in SSJS means no need to escape the ones in HTML.
- On most keyboard (including mine), it doesn't require pressing Shift each time. Clicking one button is faster.
However, there are also arguments for double quotes:
- There are many English words using apostrophes, and using double quotes means no need to escape them.
- JSON requires double quotes.
In the end, pick one, align with your team, and stay consistent. Yes, this means updating quotes after copy-pasting from Stack Overflow. RegEx is your friend ;)
Code tells you how. Comments tell you why. - Jeff Atwood
To make your code better, don't stop at just the code. Leverage comments to their full potential. Context, logic and caveats description will improve the experience for everyone - including you after few weeks.
Whenever you build more complex SSJS code, I recommend using at least three types of comments: table of contents, section and documentation. For short scripts, the last type will be enough.
The first type of comment you should use at the top of your longer scripts is the table of contents comment. This one will be your best friend during the whole lifecycle of your script.
Before even starting to write SSJS, describe the desired outcome and steps you plan to code to get there. It can be high level; it can be a draft. But it will help you focus on the best way to write your script and consider potential roadblocks or opportunities for optimisation.
As you are building your script - update the comment to reflect the approach you took. It will help you assess the impact of potential changes and find missing pieces.
To fully leverage the pseudo-code table of contents, add section comments to mark where each part of your code starts.
For complex scripts, it might be a good idea to create few different levels of such comments. I use upper case with dashes for the first level, title case with dashes for the second level and only title case for the third level of comments
Two previous comment types are suitable for high-level view and organisation of your more complex scripts. But the essential type of comment is the one that goes into detail about the implementation - the documentation comments.
You should use one for every custom function you create, but it might also benefit variables (especially those that have values coming from an API response). Rule of thumb - add them whenever someone else reading your code for the first time would ask a question about context or purpose.
I recommend using JSDoc for few reasons:
- It's a popular standard.
- It provides recommendations on what to add to the comment.
- Many code editors will help you write it and highlight its syntax.
- Marketing Cloud ecosystem already leverages it in Interaction Studio.
If you find it too complex, feel free to make it simpler, as long as your approach:
- describes context and purpose and
- is consistent across the codebase.
It is a long article, so let's gather all the recommendations in one place:
- Be consistent
- Strive for readability
- Use descriptive names to provide context 🔗
camelCasefor all elements of JS syntax 🔗
PascalCasefor all elements of SSJS syntax 🔗
- Sparse is better than dense 🔗
- Use indentation to highlight code relationships 🔗
- Use spaces wherever it makes the code more readable 🔗
- Add a semicolon after each statement 🔗
- Use single quote style 🔗
- Use comments to provide required context to your script 🔗
If you want to share something I'm missing or have arguments for a different recommendation - let me know.
Looking for more Marketing Cloud style? Check out my SFMC SQL Style Guide.