Exposing the Formatting Options with IDE Settings

[sanjana]

Currently, the Ballerina formatter is capable of configuring the tabSize, columnLimit, wsCharacter internally within the source code.
#28234 suggests that these FormattingOptions should be able to be configured by the Ballerina VSCode plugin as well.

Also, the Language Server Protocol Specification which are listed by Microsoft specifies the following Formatting Option Configurations additionally.

/**
* Prefer spaces over tabs.
*/
insertSpaces: boolean;

/**
* Trim trailing whitespace on a line.
*/
trimTrailingWhitespace?: boolean;

/**
* Insert a newline character at the end of the file if one does not exist.
*/
insertFinalNewline?: boolean;

/**
* Trim all newlines after the final newline at the end of the file.
*/
trimFinalNewlines?: boolean;

At an offline discussion, it was proposed that rather than exposing any such configurations to the user within the VSCode plugin, we should be setting a fixed set of formatting guidelines, which will be the only set of configurations that will be used when formatting Ballerina code. This was suggested with respect to the approach used by the Rust Language Specifications.

It was also pointed out that if a code is formatted using the VSCode plugin with a custom formatting options configuration, it would look different than when formatted using the Ballerina CLI tool which uses the default configuration options.
A workaround would be to pass the formatting options configurations (or a file that includes these configurations) as parameters when using the bal format command.

The implementation of #28234 is almost completed and needs to resolve the following conflicting ideas in order to proceed further.

• We should only stick with the default set of formatting option configurations and limit the capabilities of users (or not allow them) to configure the formatting options within the IDE plugins
• We shall let the users configure a specific set of the formatting options using the IDE plugins or to specify the formatting options configuration within a file

Even though the formatting only focuses on the appearance of the source code and not the execution output, it would still cause differences in collaborative projects (e.g.: when one user within a team prefers spaces over tabs there would be diffs).

@sanjiva @sameerajayasoma @Kishanthan @hasithaa @prabushi @nadeeshaan @rasika @IrushiL WDYT?

[rasika]

Let me share my view on this. We have a CLI command initiated formatting with bal format and IDE(eg.VSCode) initiated formatting.

While adding this CLI command, the idea was to adhere the Ballerina coding-convention. Thus, limited or zero customization for the user.

IDE users have the liberty of customization and they can customize line-width, 'use tab or space', 'tab-size'...etc as per their choice. Still, for the default case; Ballerina coding-convention should be applied here as well. Different IDEs can have different defaults. Thus, we cannot depend on IDE's default settings even for formatting configs such as 'use tab or space', 'tab-size'.

If we are choosing to make sure same experience between CLI and IDE we need to define our own set of Ballerina formatting options(even for 'indent with tab or space', 'tab-size'). Or else we can consider IDE's existing formatting options when formatting through the IDE.

[sanjana]

@rasika thank you very much for the response.
Currently, the Ballerina formatter works in such a way that it has a set of predefined default values for tabSize, columnLimit, etc., and once formatted (whether or not from the bal format CLI or the IDE), it would only use these default values.

But with the fix of #28234, it would be capable of formatting with the configuration options provided by the IDE's ballerina extension.

At the moment, we can have a set of default configuration options and ship these default values within the Ballerina VSCode plugin. And honor only the formatting options explicitly set by the Ballerina IDE extension/CLI parameters.

Otherwise, we can completely limit the formatting options configuration capabilities and only format according to the set of default values.

[nadeeshaan]

IMHO, formatter and the usage in different modes, depends on the IDE/ editor or even the CLI command. In each of the cases the user's expectation can be different.

Tooling vendors provide various options by default in order to alter the formatting. For example, the VSCode allows the user to set the editor configs to convert spaces to tab with the Convert Indentation to Tabs command. If the user has done this particular configuration, even if the formatter implementation enforce the user by converting the tabs to spaces, there will be no use. Because the user either have to manually trigger the command or make the behaviour automatic.

I would say, in the CLI scenario, which is a special case, the formatter can stick to the default behaviour until we support configurations via the CLI tool. In a rather contrasting situation such as using the IDEs/text editors which allows to pass the formatting configurations to the language server/ any other tooling backend, I believe it is better for the developer experience, that we support and honour the client's configurations. For an example please refer how rustfmt integration for tools work. This same formatter have been used in CLI mode (which allow configs, but in the default case it adhere to the rust styling guide) and in VSCode as well.

So for the developer experience point of view I'm +1 for the configurable usage.

[prabushi]

I'm +1 for having configurable at the IDE level, as there are IDE specific configurations that we can override to provide customization. IMO, CLI and IDE address two different user experiences, and we can provide the default formatting for CLI as CLI users might not expect enriched customizations.

I'm also +1 for having as minimum configurations as possible (as mentioned here ) to keep it simple for the user. In addition to the mentioned configurations, we might need to introduce a setting for the VSCode plugin to switch to the Ballerina default settings ignoring all the other IDE specific formatting configurations.

[KavinduZoysa]

Closing this based on #38296 (comment)