Skip to content

Update clarity-formatter.md #1807

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Spagero763 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update clarity-formatter.md #1807

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 61 additions & 100 deletions docs/build/clarinet/clarity-formatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,90 +1,58 @@
# Clarity Formatter

Based on the latest available documentation, here's the updated version of the Clarity Formatter documentation:
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line appears to be an editorial note that should not be included in the final documentation. It reads like metadata or a note to reviewers rather than actual documentation content.

Suggested change
Based on the latest available documentation, here's the updated version of the Clarity Formatter documentation:

Copilot uses AI. Check for mistakes.
Clarity Formatter
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "# Clarity Formatter" or "## Clarity Formatter" depending on the desired heading level.

Copilot uses AI. Check for mistakes.
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
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Formatting philosophy" to maintain proper heading hierarchy.

Suggested change
Formatting philosophy
## Formatting philosophy

Copilot uses AI. Check for mistakes.
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
Comment on lines +7 to +9
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullet point formatting has been removed. These lines should use markdown list syntax with asterisks (*) or dashes (-) to create proper bullet points for better readability.

Copilot uses AI. Check for mistakes.

You can customize these defaults to match your preferences.
Integration points
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Integration points" to maintain proper heading hierarchy.

Suggested change
Integration points
## Integration points

Copilot uses AI. Check for mistakes.
The Clarity formatter is available through two primary tools:
Clarity VS Code Extension
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### Clarity VS Code Extension" to maintain proper heading hierarchy (as a subsection under Integration points).

Suggested change
Clarity VS Code Extension
### Clarity VS Code Extension

Copilot uses AI. Check for mistakes.
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)
Comment on lines +17 to +19
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullet point formatting has been removed. These lines should use markdown list syntax with asterisks (*) or dashes (-) to create proper bullet points for better readability.

Copilot uses AI. Check for mistakes.

Clarinet CLI
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### Clarinet CLI" to maintain proper heading hierarchy (as a subsection under Integration points).

Suggested change
Clarinet CLI
### Clarinet CLI

Copilot uses AI. Check for mistakes.
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
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Comparison table" to maintain proper heading hierarchy.

Suggested change
Comparison table
## Comparison table

Copilot uses AI. Check for mistakes.
AspectManual formattingClarity formatterConsistencyVaries by developerUniform across the codebaseSpeedTime-consumingInstantError-proneYesNoTeam coordinationRequires a style guideAutomatic enforcement
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table formatting is broken. This line appears to be a table that has lost all markdown pipe delimiters (|), making it unreadable. The table should use proper markdown table syntax with pipes separating columns and header/body separator rows.

Copilot uses AI. Check for mistakes.
Best practices
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Best practices" to maintain proper heading hierarchy.

Suggested change
Best practices
## Best practices

Copilot uses AI. Check for mistakes.

* **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
Comment on lines +27 to +30
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullet point formatting has been removed. These lines should use markdown list syntax with asterisks (*) or dashes (-) to create proper bullet points for better readability.

Suggested change
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
- 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

Copilot uses AI. Check for mistakes.

Formatting rules in detail
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Formatting rules in detail" to maintain proper heading hierarchy.

Suggested change
Formatting rules in detail
## Formatting rules in detail

Copilot uses AI. Check for mistakes.
Function definitions
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### Function definitions" to maintain proper heading hierarchy (as a subsection under Formatting rules in detail).

Suggested change
Function definitions
### Function definitions

Copilot uses AI. Check for mistakes.
Functions span multiple lines with consistent indentation:

```clarity
(define-public (my-func
clarity(define-public (my-func
(amount uint)
(sender principal)
)
(ok true)
)
Comment on lines +35 to 40
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.

Copilot uses AI. Check for mistakes.
```

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)
)
Comment on lines +42 to 44
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.

Copilot uses AI. Check for mistakes.
```

### Let expressions

Let expressions
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### Let expressions" to maintain proper heading hierarchy (as a subsection under Formatting rules in detail).

Suggested change
Let expressions
### Let expressions

Copilot uses AI. Check for mistakes.
Bindings are placed on separate lines with consistent indentation:

```clarity
(let (
clarity(let (
(a u1)
(b u2)
)
(body-expression)
)
Comment on lines +47 to 52
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.

Copilot uses AI. Check for mistakes.
```

### Control flow (if, match)

Control flow (if, match)
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### Control flow (if, match)" to maintain proper heading hierarchy (as a subsection under Formatting rules in detail).

Suggested change
Control flow (if, match)
### Control flow (if, match)

Copilot uses AI. Check for mistakes.
Each branch receives its own line:

```clarity
(if condition
clarity(if condition
(then-expression)
(else-expression)
)
Expand All @@ -93,59 +61,52 @@ Each branch receives its own line:
value (handle-some value)
(handle-none)
)
```

### Tuples and maps

Tuples and maps
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### Tuples and maps" to maintain proper heading hierarchy (as a subsection under Formatting rules in detail).

Suggested change
Tuples and maps
### Tuples and maps

Copilot uses AI. Check for mistakes.
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,
}
Comment on lines +66 to 71
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.

Copilot uses AI. Check for mistakes.
```

## Usage examples

### VS Code integration

```json
// settings.json
Usage examples
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Usage examples" to maintain proper heading hierarchy.

Suggested change
Usage examples
## Usage examples

Copilot uses AI. Check for mistakes.
VS Code integration
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### VS Code integration" to maintain proper heading hierarchy (as a subsection under Usage examples).

Suggested change
VS Code integration
### VS Code integration

Copilot uses AI. Check for mistakes.
Enable format on save in your VS Code settings:
json// settings.json
"[clarity]": {
"editor.formatOnSave": true
}
Comment on lines +75 to 78
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "json" concatenated directly with the opening backticks and code, making it invalid markdown.

Copilot uses AI. Check for mistakes.
```

### CLI usage

```bash
CLI usage
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### CLI usage" to maintain proper heading hierarchy (as a subsection under Usage examples).

Suggested change
CLI usage
### CLI usage

Copilot uses AI. Check for mistakes.
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
Comment on lines +81 to +91
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "bash" concatenated directly with the opening backticks and code, making it invalid markdown. Additionally, all the separate bash code examples and their descriptions have been merged into a single malformed block.

Copilot uses AI. Check for mistakes.
CLI options
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "### CLI options" to maintain proper heading hierarchy (as a subsection under Usage examples or as a standalone section).

Suggested change
CLI options
### CLI options

Copilot uses AI. Check for mistakes.
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 <path>Specify a specific file to formatNo
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table formatting is broken. This line appears to be a table that has lost all markdown pipe delimiters (|), making it unreadable. The table should use proper markdown table syntax with pipes separating columns and header/body separator rows.

Copilot uses AI. Check for mistakes.
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
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Ignoring blocks of code" to maintain proper heading hierarchy.

Suggested change
Ignoring blocks of code
## Ignoring blocks of code

Copilot uses AI. Check for mistakes.
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 ))
Comment on lines +97 to 100
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block markdown syntax is broken. Code blocks should be surrounded by triple backticks (```) with the language identifier on its own line. This line has "clarity" concatenated directly with the opening backticks and code, making it invalid markdown.

Copilot uses AI. Check for mistakes.
```
Additional resources
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Additional resources" to maintain proper heading hierarchy.

Suggested change
Additional resources
## Additional resources

Copilot uses AI. Check for mistakes.

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
Comment on lines +103 to +105
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullet point formatting has been removed. These lines should use markdown list syntax with asterisks (*) or dashes (-) to create proper bullet points for better readability.

Copilot uses AI. Check for mistakes.

Important notes
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading syntax is missing the markdown hash symbols. It should be "## Important notes" to maintain proper heading hierarchy.

Suggested change
Important notes
## Important notes

Copilot uses AI. Check for mistakes.

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
Comment on lines +109 to +112
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullet point formatting has been removed. These lines should use markdown list syntax with asterisks (*) or dashes (-) to create proper bullet points for better readability.

Copilot uses AI. Check for mistakes.
Loading