DevOps[0]: The one with consistent formatting
— This is part of a series on DevOps, and making that happen with Salesforce —
WHY
Creating software is accomplished in a number of ways, with a variety of styles and methods.
As a standalone developer, you form your own rules and decide what is "right". As part of a team, that approach doesn't work as well. Different people write code using different styles, often arriving at the same outcome. Having different styles isn’t necessarily a bad thing, but inconsistent styles in a shared codebase can lead to problems onboarding new team members, finding bugs, adding enhancements, or simply performing a code review. By reducing the effort to understand and troubleshoot a shared codebase, we can increase our productivity.
As part of a team, you still need to write code, review it, and fix bugs. While having style guides provides a framework to drive consistency, it's difficult to enforce efficiently. You can’t change the coding style of all your developers overnight, but by adding automation tools, you can!
In this blog, we're going to start with code formatting, and leave code patterns for another time.
WHAT
We want to set up automations in order to have code which is formatted more consistently across all the different choices/experiences of the developers on our team.
Let’s be really clear: the goal is consistency, not “correctness”. We aren't trying to solve any age-old arguments about whether you should, or should not, “smoosh” your code. Clearly, you should not smoosh your code.
The first goal is consistency in formatting (spacing, structure, etc). In order to make this work, we're going to use the tool prettier.
prettier is simple to set up, and part of the Visual Studio Code extension: Salesforce Extension Pack (Expanded). While prettier is a powerful tool, there are some limitations that don’t allow a lot of flexibility around formatting choices. Note: The Salesforce Extension Pack (Expanded) has a couple of other formatting tools we'll try to get around to discussing at a later date.
HOW
Assumptions
For the purposes of this demonstration, we are going to assume that the team is going to use VS Code as the preferred IDE. Again, to each their own. If your developers want to use their own IDE, they can still participate by installing prettier and the other dependent packages.
You'll need the following set up (each item is a link to the appropriate download page, and opens in a new tab/window) :
- or -
This article won’t cover proper set up of the above (there are plenty of examples found on “the Googles”), but the default installations should be fine. Make sure to install them in the order they are listed to avoid issues.
The rest of the article assumes that the packages are installed. You can now start improving your DevOps workflow.
Note: Commands will be run via the terminal, within VS Code (VS Code menu: Terminal > New Terminal). Files will be edited within VS Code.
Setup
( reference: https://developer.salesforce.com/tools/vscode/en/user-guide/prettier )
I'm going to use yarn 2 (because, "new” hotness), but the same command works for yarn 1 (I only mention it because the screenshots, and configs, may reflect yarn 2):
yarn add --dev prettier prettier-plugin-apex
If you prefer to use npm:
npm install --save-dev prettier prettier-plugin-apex
Once installation is complete, you’ll see something like the following (aside from the terminal prompt customizations):
Config
The following config files have some minor edits made, from their default form. Feel free to copy the entire file, or adjust your existing files to include the changes. Under each file, I’ll point out the important pieces.
Here’s a screenshot, showing the files; don’t worry, the copypasta is below…
package.json
{
"packageManager": "yarn@3.2.4",
"private": true,
"scripts": {
"prettier": "prettier --write \"**/*.{cls,cmp,component,css,email,html,js,json,md,page,trigger}\"",
"prettier:validate": "prettier --list-different \"**/*.{cls,cmp,component,css,email,html,js,json,md,page,trigger}\""
},
"devDependencies": {
"prettier": "2.7.1",
"prettier-plugin-apex": "1.11.0"
}
}
The “scripts” section is the added piece for the package.json file. It allows you to manually run prettier on one, or more, files. Also, in the future, we’ll use it to automate some validation steps.
Salesforce.code-workspace
{
"folders": [
{
"path": "."
}
],
"settings": {
"editor.formatOnSave": true
},
"extensions": {
"recommendations": [
"esbenp.prettier-vscode"
]
}
}
“settings” is the important piece here. It can be added to your workspace file, or your user settings (“settings.json”) if you want it to apply to every workspace you use. The recommended extension is there to make it a little easier for other team members to install the Prettier extension (which you manually installed in a previous step). When they open the workspace, VS Code can suggest to install recommended extensions (if not already installed).
.prettierrc
{
"trailingComma": "none",
"useTabs": true,
"overrides": [
{
"files": "**/lwc/**/*.html",
"options": { "parser": "lwc" }
},
{
"files": "*.{cmp,page,component,email}",
"options": { "parser": "html" }
}
]
}
Here, we’re specifying the format parsers for a couple of file types. That enables us to tell prettier how to handle files that it might not otherwise understand properly. We also tell prettier to use tabs for indentation, instead of spaces, because we don’t live in the dark ages.
.prettierignore
# List files or directories below to ignore them when running prettier
# More information: https://prettier.io/docs/en/ignore.html
#
**/staticresources/**
.localdevserver
.sf
.sfdx
.vscode
.yarn
coverage/
*.xml
This file allows us to tell prettier to skip certain folders or files. This avoids processing things like static resources, helper files for VS Code, and XML files, in general. You can always use VS Code to force the formatting of a file, if needed. (Also, I added “.yarn” after the screenshot was done, so that’s not shown in the screenshot, for those paying extra-close attention)
Make it so…
Restart VS Code, just to make sure everything gets properly loaded. You should now be up and running, ready to be more consistent, as you save files. At least as far as general formatting is concerned.
Quick Example / Conclusion
Here is a screenshot of a poorly formatted, extremely contrived example class:
And, yes, that nonsense will deploy, and run, within Salesforce. But, imagine trying to debug an error related to that code. Now imagine a more realistic example, spanning 500+ lines of code, with nested “if” statements, loops, etc. Basically: nightmare fuel.
Now, here’s that same file, with prettier enabled:
You can see that the formatting has been adjusted so that spacing, and placement, is more consistent. Hopefully, it’s obvious that this is much easier to review, troubleshoot, or just to understand (even though the code isn’t anything special).
Now we’ll be able to start working on the next phase of your Dev Ops journey: tracking
Minor “Gotchas”
If code is edited in Developer Console (or anywhere without Prettier set up), and then pulled locally (using VS Code menus, or sfdx commands), formatting will not happen until the next save (or running the prettier script).
So what? Well, if you pull code down, which was edited without Prettier formatting, then push to another environment, it won't benefit from our work of setting up Prettier. It could also cause unnecessary changes within source control.
Great, now what do I do? You can do a couple of things: 1) just save the file, it will get formatted. 2) run prettier, manually, from the terminal. Remember how we set up the "scripts" within the package.json file? This is an example of a time you could use yarn run prettier (especially if you pulled down multiple files, not just one).
Owners of existing repos will want to decide whether you plan to run prettier against every file, and blindly accept a large commit to add the formatting changes, or just handle each file as it gets edited. That’s a bit beyond the scope of this article, though.
