The formatting configurations that really should be available.

[xixiaofinland]

A discussion for Ideas, thoughts, opinions on what should be in the configuration list.

The result will be amended into the Settings file

[xixiaofinland]

print_width, tabWidth, and useTab are supported in Prettier Apex, but no other options to influence the formatting style.

[xixiaofinland]

Robert Sösemann in StackOverflow mentioned these in this StackOverflow post

1. Don't wrap method parameters as extra lines
2. Have 2 blank lines between each method
3. Have blank line before last return statement
4. Leave the first line of a method always blank
5. Leave the first line of a class always blank
6. Don't enforce line length. Don't break lines. Not in code and not in SOQL.
7. Don't put an extra space between if/else/while and the brace.
8. Catch statement in an extra line

[rsoesemann]

Everything is still relevant. Why would it have changed ;-).

6 means that the tool should NEVER add line breaks. I guess a print length of 8000 should do.

[aheber]

@rsoesemann, I think #6 is interesting.

Does that me the formatter should print the entire file into a single line, should never add line breaks that didn't exist before but always respect existing line breaks, should never break a statement into multiple lines?

It seems like there are several interpretations of that. I think explaining it as having a really really long line length helps to solidify it. "Add normal line breaks between whole elements but don't break a statement into multiple lines." Does that better summarize?

[macslo]

for #7.
from https://google.github.io/styleguide/javaguide.html#s4.6.2-horizontal-whitespace

Separating any reserved word, such as if, for or catch, from an open parenthesis (() that follows it on that line

The amft works now like this and it should be default behaviour.

Example from ugly formatted code:

    for(Account a: new List<Account>() ){
        if(a.ParentId==null){
            //
        }
        else{
            //
        }
    }

it is nicely formatted by amft to:

    for (Account a : new List<Account>()) {
        if (a.ParentId == null) {
            //
        } else {
            //
        }
    }

[rsoesemann]

@aheber you are right. I just dont want a tool to restrict me to an arbitrary line length from the 70s.

[macslo]

#1 #6 It would to have an option to keep lines as they are.

• not enforce line length
• not merge the statement into 1 line. It should rather keep lines as code was written.

[thvd]

Personally I really miss a continuation indentation configuration option.

[xixiaofinland]

Thanks @thvd for your comments. I never paid much attention to continuation indentation but definitely see the need for some people.

For the formatting style that inner nodes start from the 2nd line (the four parameters in the example below), continuation indentation does make sense.

pub fn method1(
    node: &Node,
    result: &mut String,
    shape: &Shape,
    source_code: &str,
) {

I wonder if somebody might prefer have more endensed line so the inner nodes also appear in the 1st line. In this use, 2nd line should be aligned with 1st line rather than the continuation indentation configuration. I'm just thinking aloud...

pub fn method1(node: &Node, result: &mut String,
               shape: &Shape, source_code: &str,
) {

[macslo]

It would be good next line be indented by double indent_size or it should be an option to keep manual continuation indentation

pub fn method1(node: &Node, result: &mut String,
        shape: &Shape, source_code: &str) {
    //code ....
}

see:
https://google.github.io/styleguide/javaguide.html#s4.5.2-line-wrapping-indent

• Block indentation: +2 spaces
• Indent continuation lines at least +4 spaces

[xixiaofinland]

ah ok.. @macslo I thought when the 1st line has node: &Node, the 2nd line shape: &Shape should ALWAYS be vertically aligned.
Based on what you said, maybe not.

[aheber]

Normalizing keywords and semi-keywords.

public class TestClass {} looks great. PuBlIc CLaSs TestClass {} looks weird. I think these are pretty easy to solve for and maybe don't need a setting.

Extending this to something like Annotations. @isTest vs @IsTest. I would love if this formatter did, or had an option, to normalize formatting for these. This is a bit tricky because in Java these are code units and how would the formatter know the approciate casing for a code unit. In Apex we don't have any control over these and they is a fixed number of valid cases (which could expand over time). It would be greatly helpful to but case correction in place for known annotations, if something isn't recognized then print it as-is and let someone open an issue to request a new normalization be added.

Apex being case insensitive creates this mess. Both are functional but it is the kind of stuff that I really want a formatter to take care of for me, I always hate expressing the nit in code reviews and so I end up with mixed case because at the end of the day it doesn't really make a difference. I'd still like it to be consistent.

SOQL keywords are some of the least consistent of the bunch. SELECT vs. Select vs. select. I would really appreciate my code formatter making those consistent across all code. I'd be perfectly happy if this was a setting I had to enable as I expect not everyone will feel the same way I do.

[xixiaofinland]

Thanks for sharing thoughts @aheber.

I think we could start with opinionated (i.e. normalizing keywords).
If we receive significant feedback or complaints, we can then consider introducing configuration options to allow for more flexibility.

[aidan-harding]

I am strongly in favour of normalising the capitalisation like this. I think the tooling API defines a set of official symbols for this, and that's how Illuminated Cloud does it. That API is probably the best source of an official list of tokens.

The thing that IC has in its favour, though, is that each project is connected to an org. So, it can normalise custom objects and custom types. I guess what you're building works one file at a time? In which case just working on the standard ones would still be valuable.

[aheber]

Array typing should be a preference.

Some organizations prefer List<Integer> and some Integer[] and it would be nice if the formatter could be configured to enforce that.

Warning: keep in mind that Integer[0] is not the same and I don't think it has a valid translation into typed generic syntax.

[xixiaofinland]

there were discussions in prettier apex:

• Prettier probably should not be transforming new List constructors dangmai/prettier-plugin-apex#262
• Array notation being transformed to List dangmai/prettier-plugin-apex#115

But i'm not sure if it's a good idea to prefer one style over the other and auto-change them. My style is List<Integer>, but I might be annoyed if I preferred Integer[] and can't do it...

[nawforce]

We use Prettier on everything, standard config is:
"printWidth": 100,
"singleQuote": true,
"tabWidth": 4,
"trailingComma": "none",
"useTabs": true

This might not be popular, but I like that there are minimal options, the more you provide the more individual teams will want to 'tune' and the more variation we need to cope with. Prettier does not create the nicest looking code, but IMO its much better than having lots of variation and devs having to deal with code review comments about formatting.

[aidan-harding]

I don't like Prettier, but that's what I've ended up using to keep it consistent across the team who use different editors. I actually thing that the built-in formatter of Illuminated Cloud with default options is the closest to my ideal behaviour.

The standout things that I care about are:

1. Ugly things can/should look ugly. If you've written a method with 10 parameters, your formatter has put one parameter per line, and you don't like it.... Then don't complain about the formatter. Stop writing methods with so many parameters.
2. Implied from 1: Line length matters. I disagree with Robert on this. Lots of long statements can be naturally broken into separate lines e.g. SOQL where there's a new line for each keyword. Or builder methods with a line per method call. If your long line can't be broken up, I think that's a design problem not a formatting one.
3. The number of levels of indentation that it can format matters. For a long time, Illuminated Cloud had a limit on this, so the indentation eventually became flat where it should have kept getting deeper. Arbitrary limits like that are bad. The limit should be the overall line width. If your statement is so indented that it doesn't fit in the line width, then the developer needs to rethink it.

Here's what we use with Prettier:

{
    "trailingComma": "es5",
    "semi": true,
    "singleQuote": true,
    "tabWidth": 4,
    "jsxSingleQuote": true,
    "bracketSameLine": true,
    "arrowParens": "always",
    "bracketSpacing": true,
    "endOfLine": "auto",
    "printWidth": 120,
    "quoteProps": "as-needed",
    "proseWrap": "never",
    "plugins": ["prettier-plugin-apex", "@prettier/plugin-xml"],
    "overrides": [
        {
            "files": "**/lwc/**/*.html",
            "options": { "parser": "lwc" }
        },
        {
            "files": "*.{cmp,page,component}",
            "options": { "parser": "html" }
        }
    ]
}

[xixiaofinland]

the #3 I'm not sure if I get it. @aidan-harding

As an example below, do you mean not only innerMethod2() should be line wrapped, but also innerMethod3() and all the nested inner nodes as long as they exceed the defined max_line_ width?

String result = outerMethod(
            innerMethod1(
                param1, 
                innerMethod2(param2, innerMethod3(paramX, paramY), param4)
            ), 
            anotherMethod(param5, param6), 
            finalMethod(param7, param8)
        );

[aheber]

Maybe already obvious but I thought I'd put it here for others to weigh in on.

One big part of adoption for me will be knowing what settings to apply for this to produce the same formatted output as Prettier-Apex. I think it would be harder for me to convince an entire team to switch over right away. If I could benefit from using this tool instead of Prettier-Apex out of the gate on my personal machine without disrupting the project then I'd could (when it is production ready) switch over right away and not have to migrate co-workers, CI Pipelines, etc... all at the same time. This would lower the barrier for adoption a lot.

Making it a drop-in replacement would appeal to me when making a case for others to switch and I could win many small battles instead of having to spend weeks or months prepping for a migration.

Imagine if I controlled the CI server and all I did was switch in this binary (because I could run this on the entire codebase, then run Prettier in --check mode and know for sure that nothing changed), I could save a lot of runtime minutes without having to change any coworkers setups, it would be an instant win.

[xixiaofinland]

I also thought about this a lot, it's definitely a solid idea and I should take it into implementation. There remain a couple of challenges:

1. it seems Prettier doesn't have a hard limit max_width on line wrapping. It becomes a black box for me.

Prettier’s printWidth option does not work the same way. It is not the hard upper allowed line length limit. It is a way to say to Prettier roughly how long you’d like lines to be. Prettier will make both shorter and longer lines, but generally strive to meet the specified printWidth.

2. Array notation. PA(Prettier-Apex) automatically updates the code from style a to style b, which I don't think afmt should do, should I? Brian elaborated it on a bigger scope here . I recall we have discussed this somewhere before, do you happen to remember the URL? @aheber

a: Integer[] a = new Integer[]{1, 2, 3, 4};
b: Integer[] a = new List<Integer>{ 1, 2, 3, 4 };

4. Single line if while statement. Afmt at the moment automatically adds the missing block brackets into if (true) { System.debug('hello'); } while PA doesn't. I think it's better to do so as this both helps simplify the formatting logic and enforce coding best practice. Or maybe this could be a configuration option in .afmt.toml....

if (true) System.debug('hello');

[aheber]

I imagine #4 will be a big deal for some. I personally prefer adding the brackets but I'm also sure others will be frustrated by it. So many bugs caused by leaving the brackets off. In a perfect world I'd make that a linting issue rather than a formatter issue.

#2 are you talking about here where you brought up the two AP issues? As stated in those issues, I don't like that Prettier does that. Is this a "line in the sand" moment or do you optimize for adoption? Making it easy to transition at the cost of complexity and maintenance burden?

My thoughts, if you're not going to be able to be 100% percent compatible then don't go out of your way to be 99% compatible. If there is any barrier to entry then it doesn't matter much how big it is. If I have to reformat my codebase for anything then it likely doesn't matter if it is big or little. (That probably isn't true for all, taking on a new tool would likely include manually reviewing it's initial formatting commit)

I'd personally prefer a given file is reformatted when it is edited but I know a lot of people get really bothered by all the non-relevant changes when trying to do code reviews. (I'll gladly admit it makes it harder)

[xixiaofinland]

well said @aheber, I will explore more when I start the line-wrapping implementation.

[aheber]

I don't think this has come up yet but what about empty classes?

My preference is empty blocks to end on the same line. Take the following

global class Me {
  global class MyException extends Exception {
  }
}

I would prefer it be formatted as

global class Me {
  global class MyException extends Exception {}
}

I have created a lot of custom exception classes and it bothers me every time the closing brace is on another line. Maybe there are really good reasons you're doing it (Prettier-Apex has the same behavior but it was explained as more of an implementation detail than a decision)

Maybe a setting? Of course if you simply choose it as a behavior then you won't be able to format identical to Prettier-Apex, going back to the decisions and strategy portion.

[xixiaofinland]

this should be a fairly easy implementation and I do think it's a valid point.

added in the list
https://github.com/xixiaofinland/afmt/blob/main/doc/Settings.md#empty_item_single_line