Contents
Clarity is a relatively new programming language that was specifically designed for smart contracts. It’s a powerful language with unique features: it has read-access to Bitcoin chainstate, and it is optimized for security, decidability, and transparency (useful traits for contracts that need to be trusted and remain resilient against bad actors).
But, since Clarity is a young language, there aren’t well-defined standards for how that code should be formatted. And to date, Stacks developers have taken many different approaches to formatting their code (or sometimes not formatting at all). This introduces additional friction for new developers that are learning Clarity: it’s harder to parse the code of existing contracts and learn from apps already in production.
We’re trying to fix that and introduce standards for Clarity formatting.
In February, we launched a Clarity formatter in Clarinet that introduced an initial version of Clarity formatting standards, with the intention that these standards would evolve over time based on community feedback.
Since then, we’ve been collecting feedback to understand what you liked and didn’t like about these initial standards, and today, we’re excited to announce that we have rolled out this Clarity formatter to the Clarity VS Code extension, along with some stability improvements.
Current Formatting Standards
The Clarity formatter implements an opinionated formatting standard with configurations for line wrapping and indentation:
- Lines will be wrapped at 80 characters.
- Indents will be 2 spaces.
These default settings are both configurable, and you can set these values to your preference.
Alongside these settings, the Clarity formatter introduces formatting rules for many of the basic Clarity constructs, such as:
- <code-rich-text>let<code-rich-text>
- <code-rich-text>begin<code-rich-text>
- <code-rich-text>match<code-rich-text>
- Tuples and map sugar
- <code-rich-text>if<code-rich-text>
- <code-rich-text>and<code-rich-text>/<code-rich-text>or<code-rich-text>
- Trailing comments
- public/read-only/private functions
- constant/persisted-variable/ft/nft/impl-trait/use-trait
- <code-rich-text>define-map<code-rich-text>
- <code-rich-text>define-trait<code-rich-text>
If you want to ignore a specific code block with the formatter, you can precede that block with a comment <code-rich-text>;; @format-ignore<code-rich-text>.
Here’s a comparison of how this formatting looks in practice.
Unformatted code:
Formatted code:
For examples of well-formatted contracts, check out these sample contracts and view the formatting rules in our documentation.
VS Code Support
We have added the Clarity formatter to the Clarity VS Code extension for the first time, so you can now leverage these formatting standards when building in VS Code.
With VS Code, you can configure formatting on-demand or on-save. You can even “format section”, which will only format the code that you highlight.
Format on-save can be enabled in VS Code settings and is set to <code-rich-text>off<code-rich-text> by default.
Contract Formatting in the CLI
With the Clarinet CLI, you have all of the capabilities mentioned above, but you can also format all contracts within your project based on your project’s manifest. You can learn more about that in documentation.
Try It Out
This Clarity formatter is still in its early stages. Please use it with caution and let us know what you think, so we can continue to improve these standards for you and the wider Stacks ecosystem.
For more information, please read the documentation and the Clarity formatter readme.
