Project overview & release timeline

[rvanasa]

Motoko Formatter

This document outlines the functional requirements and release timeline for the first version of the official Motoko code formatter.

Abstract

A code formatter converts source code from one format style to another. This is relatively straightforward because of the unambiguous syntax of programming languages. Code beautification involves parsing the source code into component structures, such as assignment statements, if blocks, loops, etc.

There currently does not exist a code formatter for the Motoko programming language. Building one is of high importance then, due to its impact on developer experience and effect on usability of Motoko by developers coming from more established languages.

Such a formatter can be used by developers who use integrated development environments that support third-party plugin systems and supply an interface for code formatting functionality.

Functional Requirements

1. formatter is “line-width aware” - reformats code such that lines exceeding a specified width are wrapped onto multiple lines
2. formatter automatically repositions the cursor in the expected location after a format operation takes place
3. formatter configures whitespace around tokens
4. formatter converts single quotes to double quotes where applicable
5. formatter automatically inserts semicolons where needed
6. formatter aligns indentation levels for each line of code such that each line’s indentation is homogenous respective to its block
7. formatter respects user-defined configuration for numerous parameters (see IntelliJ formatter for inspiration)

Non-functional Requirements

1. formatter is published as an NPM package
2. formatter should have an automated CI process using Github actions that can auto publish based on some condition (e.g. PR is merged into “release” branch)
3. formatter conforms to the Prettier interface standard
4. formatter functionality is integrated with the existing Motoko plugin for VSCode
5. All related repositories are migrated to github.com/dfinity organization
6. formatter is published as an Intellij plugin
7. focus groups are established to gather feedback

Timeline

Iteration 1

Estimated completion: Aug 26, 2022

• [x] #2
• [x] #3
• [x] #6
• [x] #15
• [x] #4

Iteration 2

Estimated completion: Sep 9, 2022

• [x] #7
• [x] #8
• [x] #5
• [x] #16
• [x] #17

Iteration 3

Estimated completion: Sep 23, 2022

• [x] #10
• [x] #14
• [x] #44

Beyond

• [x] #9
• [x] #11
• [x] #12
• [x] #13

[rvanasa]

Transcribed from a Google Doc to track our progress with the code formatter. Open-source contributions are welcome!