Cadence formatter

[bartolomej]

Category

• Open source maintenance
• Developer tools / services
• Educational material

Description

Cadence formatter is already in the later stages of development. Still, it's missing a few things necessary for the first public release - particularly, retaining comments in the formatted output.

In the scope of this grant, I intend to complete the formatter development and integrate it into the various ecosystem tools so we can release it to the community.

Links

Primary issues to be solved (early milestones):

• Implement pretty print for Cadence cadence#209
• Retain comments in AST cadence#308

Follow-up issues (later milestones):

• Pretty print adding extra parenthesis  cadence#2776
• Beautify Cadence vscode-cadence#72

Existing work (WIP):

• [WIP] Retain comments in AST cadence#3509

Problem statement

Manually formatting code is annoying and tedious work, so some developers mostly skip it and leave the code in a less readable state, while others invent their own custom formatting rules/guidelines, which makes the code readable but incompatible with the custom rules of other developers.

That's why most (all) production-quality programming languages provide an official (or a community-based) tool that uses an opinionated set of rules to format the code consistently.

I believe implementing such a tool for Cadence is important for the maturity of the language/ecosystem and will lead to the benefits mentioned above.

Target audience

• Every developer using Cadence

Evidence for the need

• Cadence contracts are formatted manually, which leads to inconsistent style
• No formatting tool has been built or adopted yet

Proposed solution

Retain comments in the AST and include them in the formatted output. Resolve any remaining issues and prepare for the release.

Impact

Cadence source code of any project will have a consistent / easy-to-read style, making it easier for all developers to use and develop using Cadence.

Milestones and funding

Milestone	Description	Deliverables	Timeline	Risks	USD proposal
1 - Retain comments in AST	• Refactor trivia tracking in lexer/AST • Track comments for all (relevant) AST nodes.	AST decorated with comments, ready to be pretty-printed	4 weeks	-	7,000
2 - Pretty-print comments	• Given the decorated AST nodes, include leading/trailing comments in the pretty-printed output. • Fix any remaining issues and tests to make the formatter fully working.	Complete pretty-printed output	3 weeks	-	5,000
3 - Testing on production code / bug-fixing	• As mentioned by Jan, a good benchmark for prettier is to test against all mainnet contracts, so I plan to set up a test suite that does just that. • Add unit test cases for interesting edge cases (e.g. found in production code)	Reliable behaviour	3 weeks	Encountering unexpected issues and edge-cases	5,000
4 - Community feedback, resolve remaining issues	• Reach out to the community with an early beta version, so that users can give feedback on the desired output / unexpected behaviors. • Resolve any remaining issues that would be a breaking change (in terms of the formatted output) if we introduce them after the tool is released (which won’t be great as it would introduce unnecessary changes in VCS).	Community-approved behaviour	3 weeks	-	3,000
5 - Integration with ecosystem tooling, documentation, adoption	• Integrate formatter in Flow CLI • Integrate formatter in VsCode extension via the formatting API • Add the necessary documentation • Help integrate formatter in existing tools/apps (e.g. Contract Browser, Playground,…) • Advocate prettier tool and help with adoption	Prettier in production	4 weeks	-	5,000

Total funding proposed: $25,000

Team

Name	Role	Bio	Contact
Bartolomej Kozorog (aka. Bart)	Software Engineer	Passionate engineer, who loves working on interesting projects	[email protected] / 0xbartek on Discord

[bartolomej]

@franklywatson I'm making good progress on the first PR for retaining comments in the AST. Any chance we can get this grant reviewed/approved so that I can put more focus into this and confidently continue my current work?