Style Formatting with VS Code
There are different style formatters out there that can take a file containing your code as input and return a file that is formatted style-wise. To get more out of the process you can
- integrate a formatter with an IDE
- compare and contrast the changes made by the formatter using Git diffing
- specify additional settings of the formatter before formatting
As the title says, we will be using VS Code as our IDE for this article. Also, to be clear before we continue, linting and formatting are different and are not interchangeable terms. See Linting vs Formatting: A Swift Guide. The style of this article tries to be beginner-friendly, so if you read something that is already quite familiar to you, simply read through it or skip it. However, this article presumes that you know some basics of how to use Source Control.
Integrating a formatter with VS Code
The keyboard shortcut for applying style formatting to an entire document in VS Code is Shift+Alt+F. If you want to apply it to selected text only, it is Ctrl+K followed by Ctrl+F. The first time you do this with a document written in Python, this message pops up at the bottom right:
It gives you the choice of choosing to install either yapf, autopep8, or black. I will not go into detail about what differs between the three but you can read a brief summary of it here. A similar thing happens with other languages. For instance, this is what shows up with a .cpp file:
After installing a formatter, you can now use the Format Entire Document or Format Selected Text commands, using their keyboard shortcuts or the command palette, to run the formatter on the active document or selected text. After formatting is complete you will have style changes on the document that are yet unsaved.
On the other hand if the document is written in HTML, VS Code is equipped with a formatter out of the box and will immediately format your code without asking you to install a formatter. It is based on js-beautify, which means that it can also handle JavaScript! (The code in this article’s preview image is in JavaScript)
Reviewing style changes with Git diffing
To easily confirm and identify all the changes that have been made, you can make use of Git diffing.
At this point, after you have run a formatter on your document, you have unsaved style changes. Save the file so that it is listed as a modified file when you go to the Source Control tab of VS Code on the left bar. The capital ‘M’ on the right of the filename stands for ‘Modified’.
Click on the file to display the Git diff of the file and review the highlighted changes. As you’re going over the changes, most likely, you are going to see some changes that you don’t want or don’t agree with. Don’t worry because you can choose which changes you want to keep and which changes you want to discard.
If you want to keep most of the changes
If the majority are changes that you want to keep, stage all the changes in the file. Then, on the modified version of the document (the one on the right), unstage the individual changes that you don’t want. You do this by selecting the lines that have changes you don’t want, right-clicking on the selection, and then clicking on Unstage Selected Ranges.
After you have unstaged all of the changes that you don’t want, you can now make a commit.
If you don’t want to keep most of the changes
If the majority are changes that you don’t want to keep, do not stage all changes in the file. Instead, on the modified version of the document, stage only the changes that you do want to keep. You do this by selecting the lines that have changes you want, right-clicking on the selection, and then clicking on Stage Selected Ranges.
After you have staged all of the changes that you don’t want, you can now make a commit.
Fine-tuning the formatter’s behavior
With most formatters, it’s possible to switch the default formatting style to another predefined style, or even make your own small adjustments to the formatter’s behavior. A formatter’s documentation will have instructions for this. However, since this is a VS Code article after all, we will discuss VS Code-specific ways to do this.
Configuring formatter behavior through VS Code’s interface
Often, you can configure a formatter’s behavior in VS Code’s Settings. You can find VS Code Settings by going to File > Preferences > Settings. Once at the Settings page, you will see two tabs: User and Workspace. From VS Code’s documentation on Settings:
VS Code provides two different scopes for settings:
User Settings — Settings that apply globally to any instance of VS Code you open.
Workspace Settings — Settings stored inside your workspace and only apply when the workspace is opened.
Make sure to select the tab of the scope you want, User or Workspace, before modifying Settings. If you don’t know what Workspaces are or how to initialize one, see a VS Code doc here, and a stack overflow question here.
For some formatters, adjusting its settings through VS Code is more fleshed out in VS Code’s interface, while less so for others. For instance, for HTML, you can find the default formatter’s settings by going to the Settings page and then going to Extensions > HTML. Once here, you have a set of checkboxes and dropdown lists to tinker with in order to get the settings that you want.
While for Python, the formatter settings can also be found at the Settings Page in Extensions > Python, and it looks like this:
Note that there are no checkboxes and dropdown lists. Instead, you are being asked to add a list of Args, which is shorthand for Command Line Arguments. For the formatter that you have chosen to use (Black/Yapf/Autopep8), you will have to consult that formatter’s documentation to look at its arguments. For example, in yapf documentation, here are some arguments that you can add to toggle certain behaviors:
Configuring formatter behavior through settings.json
So far, we’ve discussed how to look at and configure settings through VS Code’s interface. The other way to actually do it is through VS Code’s settings.json files. See this section of a VS Code doc to see where the User and Workspace settings.json files are located. When you configure settings in VS Code’s interface, these files are modified. If you know what you’re doing, you can modify these files yourself. You may have to consult documentation to know what to modify or insert. For example, the settings.json line equivalents of the HTML formatter settings can be found in VS Code’s docs here.
References
- yapf page on PyPI.
- HTML in Visual Studio Code. From official VS Code Documentation.
- User and Workspace Settings. From official VS Code Documentation.
- What is a VS Code “workspace”?. From official VS Code Documentation.
