From 4b6d0825b8e1f47724ea668c3cabce7984488d89 Mon Sep 17 00:00:00 2001 From: Afolabi Ayomide Emmanuel <138625749+Spagero763@users.noreply.github.com> Date: Mon, 26 Jan 2026 03:49:26 +0100 Subject: [PATCH] Update clarity-formatter.md --- docs/build/clarinet/clarity-formatter.md | 161 +++++++++-------------- 1 file changed, 61 insertions(+), 100 deletions(-) diff --git a/docs/build/clarinet/clarity-formatter.md b/docs/build/clarinet/clarity-formatter.md index 8a0cfb218f..da2f44696f 100644 --- a/docs/build/clarinet/clarity-formatter.md +++ b/docs/build/clarinet/clarity-formatter.md @@ -1,90 +1,58 @@ -# Clarity Formatter - +Based on the latest available documentation, here's the updated version of the Clarity Formatter documentation: +Clarity Formatter The Clarity formatter automatically shapes your smart contract code to follow standardized style rules. Consistent formatting improves readability and makes collaboration easier across teams. - -## Formatting philosophy - +Formatting philosophy The formatter applies an opinionated standard designed to make Clarity code more readable: -* **Line length** – wraps lines at 80 characters by default -* **Indentation** – uses two spaces for consistency -* **Structure** – enforces consistent patterns for functions, let bindings, and control flow +Line length – wraps lines at 80 characters by default +Indentation – uses two spaces for consistency +Structure – enforces consistent patterns for functions, let bindings, and control flow You can customize these defaults to match your preferences. +Integration points +The Clarity formatter is available through two primary tools: +Clarity VS Code Extension +Format directly in the editor with support for: -### Integration points - -{% stepper %} -{% step %} -#### Clarity VS Code Extension - -Format directly in the editor. -{% endstep %} - -{% step %} -#### Clarinet CLI +Format on save (disabled by default) +Format on demand +Format selection (format only highlighted code) +Clarinet CLI Format via command line, including entire projects. -{% endstep %} -{% endstepper %} - -## Comparison table - -| Aspect | Manual formatting | Clarity formatter | -| ----------------- | ---------------------- | --------------------------- | -| Consistency | Varies by developer | Uniform across the codebase | -| Speed | Time-consuming | Instant | -| Error-prone | Yes | No | -| Team coordination | Requires a style guide | Automatic enforcement | - -## Best practices +Comparison table +AspectManual formattingClarity formatterConsistencyVaries by developerUniform across the codebaseSpeedTime-consumingInstantError-proneYesNoTeam coordinationRequires a style guideAutomatic enforcement +Best practices -* **Format on save** – enable automatic formatting in VS Code -* **Pre-commit hooks** – ensure code is formatted before commits -* **Team adoption** – share consistent settings with your team - -## Formatting rules in detail - -### Function definitions +Format on save – enable automatic formatting in VS Code settings (set to off by default) +Format checks in CI/CD – use --check flag to validate formatting in pipelines +Team adoption – share consistent settings with your team +Format entire projects – use Clarinet CLI to format all contracts in your project +Formatting rules in detail +Function definitions Functions span multiple lines with consistent indentation: - -```clarity -(define-public (my-func +clarity(define-public (my-func (amount uint) (sender principal) ) (ok true) ) -``` - Single arguments can remain on the first line: - -```clarity -(define-read-only (get-balance (who principal)) +clarity(define-read-only (get-balance (who principal)) (ok u0) ) -``` - -### Let expressions - +Let expressions Bindings are placed on separate lines with consistent indentation: - -```clarity -(let ( +clarity(let ( (a u1) (b u2) ) (body-expression) ) -``` - -### Control flow (if, match) - +Control flow (if, match) Each branch receives its own line: - -```clarity -(if condition +clarity(if condition (then-expression) (else-expression) ) @@ -93,59 +61,52 @@ Each branch receives its own line: value (handle-some value) (handle-none) ) -``` - -### Tuples and maps - +Tuples and maps The formatter automatically converts to sugared syntax with proper formatting: - -```clarity -;; Input: (tuple (n1 u1) (n2 u2)) +clarity;; Input: (tuple (n1 u1) (n2 u2)) ;; Output: { n1: u1, n2: u2, } -``` - -## Usage examples - -### VS Code integration - -```json -// settings.json +Usage examples +VS Code integration +Enable format on save in your VS Code settings: +json// settings.json "[clarity]": { "editor.formatOnSave": true } -``` - -### CLI usage - -```bash +CLI usage +Format files with standard options: +bash# Format and modify files in place clarinet format --in-place -``` - -Format with custom settings: - -```bash -clarinet format -i 4 -l 120 --in-place -``` -Check formatting in CI/CD pipelines: +# Format a specific file +clarinet format --file contracts/token.clar --in-place -```bash +# Check formatting without modifying files (ideal for CI/CD) clarinet format --check -``` - -The `--check` flag validates that all Clarity files are properly formatted without changing them, which is ideal for continuous integration workflows. - -## Ignoring blocks of code -Prevent formatting for specific code blocks: - -```clarity -;; @format-ignore +# Preview formatting changes without modifying files +clarinet format --dry-run +CLI options +OptionShortDescriptionRequired--checkCheck if code is formatted without modifying filesNo--dry-runOnly echo the result of formattingNo--in-placeReplace the contents of a file with the formatted codeNo--file Specify a specific file to formatNo +The --check flag validates that all Clarity files are properly formatted without changing them, making it ideal for continuous integration workflows. +Ignoring blocks of code +Prevent formatting for specific code blocks by preceding them with a comment: +clarity;; @format-ignore (define-constant something (list 1 2 3 ;; Preserves custom spacing 4 5 )) -``` +Additional resources + +Sample contracts – View well-formatted contract examples in the Stacks ecosystem +Formatter README – Detailed technical documentation about the formatter +Official documentation – Visit the Stacks documentation for comprehensive guides + +Important notes + +The Clarity formatter is actively evolving based on community feedback +Format on save is disabled by default in VS Code to give developers control +The formatter helps enforce best practices for let bindings and other Clarity constructs +Use caution when first adopting the formatter and review changes before committing