Jaxrs-api: Formating Rulesets for IDEs

[mkarg]

It would be great it one would find the time to donate some formatting ruleset files for IDEs, matching the currently applied formatting style of the existing code. This makes it easier for hacking the code with the IDE of choice. :-)

[mkarg]

@spericas To make this task easier, could you donate the IDE formatting ruleset that you personally used back then when you wrote the original code? That would be terrific. :-)

[spericas]

@mkarg I don't believe I have those exact rules, but let me poke around and see if I can find something close.

[mkarg]

@spericas I assume you simply applied the original Sun Java rules? Or did Oracle have a different company style?

[ghost]

So far I only know of editoroconfig to accomplish something like this. Any other ideas ?

[mkarg]

@rogergl Eclipse for example can export the complete set of formatting rules as a single file. Possiby other IDEs can do the same. The actual problem infact is that nobody knows what the settings have to look like. So to solve _this_ issue, one has to go through all the settings of his IDE and tune them as long as the formatting outcome produces a more or less empty git diff to master's HEAD. Once that is done, others can try to apply the same rules to other IDEs. So in the end, we will have one PR for Eclipse, one PR for NetBeans, etc.

[ghost]

@mkarg Ok I could test for IntelliJ. Nevertheless I think it would make sense to provide a simple .editorconfig. That would at least help some users of non IDEs (Visual Code, Vim) and would provide a common basic config across different IDEs.

[mkarg]

@rogergl A PR with a .editorconfig would be terrific, but please take care that it will match the _existing_ code style as perfect as possible. I want to split up the creation of the config file from the discussion about _changing_ the style.

[arjantijms]

but please take care that it will match the existing code style as perfect as possible.

I don't think there really is an existing code style yet, is there?

So let's establish that style first, and then create a formatting ruleset for it that at least partially matches that style. Partially, since most IDEs probably don't have formatting that applies all rules (i.e. I think Eclipse has no formatting to automatically apply the modifier like `private static final).

[mkarg]

@arjantijms The plan is to _fix existing_ things first and change them later _if needed_. So if you simply _want_ to change the style then please start a separate discussion in a separate issue but do not stop contributors from working on this one. Thanks.

There definitively is an existing code style as there is existing code and a short check using Eclipse tells us that it seems to be a rather simple deviation of the original Sun style.

[arjantijms]

It doesn't really seem there is a clearly defined style I think, as it was needed to ask the following question:

I assume you simply applied the original Sun Java rules? Or did Oracle have a different company style?

With the check style rules warning about things that are not in the code, it looks like it's definitely not that clear cut.

Maybe it's a simple deviation, maybe not. If only a a short check has been done that's perhaps a bit hard to say. Plus, the deviation would need to be clearly identified before going ahead with creating formatting rules for the IDEs for that.

Probably it's a bit more productive to put this issue on hold, define the overal style first, then go ahead with creating rule sets for all the IDEs. It might be as simple as saying Sun style + JavaDoc formatting in style X (Sun style is not explicitly clear about this).

[mkarg]

Yes, the existing style _might or might not_ be well specified. We do not know until we try to find out.

And no, it is definitively _not_ more productive to start a lengthy discussion about the likes and disliked of everybody first. It just keeps everybody away from work. It particularly is the wrong place to start a discussion about _new_ rules in an issue that simply tries to get along with the _existing_ rules.

Again: If you want a different style, then feel free to open a _separate_ issue, assign it to you, and drive that discussion. If you come up with a clear definition of a new style one fine day then it will get accepted after three +1 and no -1 reviews. Not earlier. Good look.

Until then, please let me and the other contributors simply do our job by _keeping the existing_ style -- as unclear and unspecific it might be defined.

[arjantijms]

I'll start that discussion indeed, as I already mentioned.

I'm fine with keeping the code formatted as it is right now, but I'm not sure it makes much sense to define formatting rules for a style that isn't defined.

I mean, how would you go about doing that? The only way to really format the undefined style is to not format it (not touch the existing formatting), which as mentioned above I'm fine with.

So I think it's best not to needlessly take resources away from people by asking to specify rules for this unspecified style, but instead use those resources to define a style first, and then from that style create rules for the 3 well known IDEs.

[mkarg]

We're not taking any resources way from other tasks: The contributor currently working on this issue is a newbie in this project and there is nothing better for him to start with anyways. No need to make up _your_ mind about the guys _I_ toss into the project. ;-)

The job is easier as you might think. I already reformatted using the built-in formatters of Eclipse IDE and noticed that some match rather well. Not ideal, but acceptable. One just need to adjust a few screws and the job's done.

Once your discussion is over, you then can just adjust a few other screws of the existing .editorconfig file then instead of starting one from scratch.

[arjantijms]

Newbie or not, if the current formatting is inconsistent you can't create matching rules for it. Put differently, there are no rules for chaos.

Any rules that you do create and that when applied change the formatting would have implicitly defined a formatting rule, which I would rather like to define explicitly first.

There's no need to start totally from scratch. The best convention would be one that's already well known and widely used, with a few tweaks where necessary. Based on the Eclipse formatter that would be:

Build-in Eclipse conventions (which are quite close to Sun) with:

• Spaces only
• Indentation size 4 spaces
• Maximum line width 160
• Maximum width for comments 120
• No indent of Javadoc tags
• No newline after @param tags

This doesn't cover builder/functional style parts yet, but would be a good start (Eclipse doesn't really have a formatter for builder style, but one initially formatted you can tell Eclipse to leave it alone by using the "never join already wrapped lines" option)

[mkarg]

I never said somebody shall start from scratch. Certainly it makes sense to pick Eclipse/Sun and check what screws to turn on. I bet it will match 99% of the existing code of this project (and any other project is out of scope of _this_ issue).

Also I won't say that _this_ project's existing formatting is totally chaotic.

[roger-gl]

just tried the IntelliJ formatter. There a lot of differences but most of the time it's 'unused imports' , missing blank lines in import and wrong formatting in javadocs and a missing blank after if. Not sure if this info helps...

[arjantijms]

@roger-gl that sure helps indeed.

I think trying to adjust the IntelliJ formatter in such way that when you apply the formatting you get zero changes is a bit of a waste of time, but we've been discussing this for a bit here without asking what you yourself would actually think about doing that. So I'm curious what you think.

[ghost]

@arjantijms I'm not sure. From what I remember the default formatter setting in Eclipse and Intellij do not differ that much. Therefore just defining an editorconfig with the basic settings will be enough and than leave it to the individual programmer that his or her changes do not cause to many changes just because of formatting issues ?

[arjantijms]

@rogergl An editor config with basic settings would unfortunately not satisfy the earlier set task of trying to find a ruleset that exactly matches the existing formatting. I.e the task is not defining a ruleset, but more documenting the existing formatting using formatting rules.

But as mentioned, I feel that's not really a useful task.

Instead, there's now a formatting recommendation that should be easy to define an editconfig for. See https://github.com/eclipse-ee4j/ee4j/wiki/Code-Conventions

I propose to make an editorconfig for those conventions instead of trying to document in an editconfig what the existing formatting is.

[ggam]

+1. And once done, that editorconfig could be moved to the wiki so that
other projects can directly benefit from it.

El sáb., 14 abr. 2018 10:18, Arjan Tijms [e-mail]
escribió:

@rogergl https://github.com/rogergl An editor config with basic
settings would unfortunately not satisfy the earlier set task of trying to
find a ruleset that exactly matches the existing formatting. I.e the task
is not defining a ruleset, but more documenting the existing formatting
using formatting rules.

But as mentioned, I feel that's not really a useful task.

Instead, there's now a formatting recommendation that should be easy to
define an editconfig for. See
https://github.com/eclipse-ee4j/ee4j/wiki/Code-Conventions

I propose to make an editorconfig for those conventions instead of trying
to document in an editconfig what the existing formatting is.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/eclipse-ee4j/jaxrs-api/issues/601#issuecomment-381312753,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACAucE22Qz15edNwJvvQ7ngGolOlM1zVks5tobDrgaJpZM4SuzET
.

[ghost]

@arjantijms +1

[ghost]

I finale had some spare time. The following .editorconfig works

charset=utf-8
end_of_line=lf
insert_final_newline=false
indent_style=space
indent_size=4
max_line_length=160

But not sure if that is really helpful.

[mkarg]

Thanks for this initial proposal. Looking at the lot of settings Eclipse and other IDEs actually consider when formatting the code, I really doubt that these six ones will fulfil the intended purpose.

[wesleyegberto]

Hi All,
I don't know if you still need an Eclipse settings to follow EE4J rules (as @arjantijms said) but I tried to follow the rules.

Here are some notes:

• Maximum width for comments is 120, counting from start of line;
• Kept empty anonymous class inline (like new GenericType<ArrayList<String>>() {});
• Preserved spaces in trailing comments;

To reduce the git changes I kept the following rules:

• Inline array declaration without space between its braces and elements (like {1,2,3} - because all annotations);
• Disabled line comment format;
• Indentation inside a switch block;
• Simple if on one line;
• Checked option 'Never join already wrapped lines' to keep the current format in some classes;

Here is the resume of changes:

• Removed empty line between members or at EOF;
• Inserted blank line between member and the following member's JavaDoc (where there wasn't any);
• Inserted space between if and opening parenthesis;
• Inserted space between closing parenthesis of a method and its opening brace (one file);
• Indented method's parameteres which was on new line;

You can check the changes in this commit.

I also commited the Eclipse settings here, so you can get and fix any problem.

I know that Intellij can import the exported rules from Eclipse and using VSCode (with this Java plugin from Red Hat) we can point to it, but I'm not sure about Netbeans.

Hope I could help

[chkal]

@wesleyegberto Thanks a lot! This looks great!

I don't know what others think, but if these settings are close to the current code format used, we could ask @wesleyegberto to create a pull request and start using this format for new code. Not sure if we really should apply the format to the existing code. Especially because details of the formatting will always differ between Eclipse, IntelliJ and so on.

[mkarg]

In my opinion we should do a complete reformatting of all existing code between JAX-RS 2.2 and 3.0, and then force this format using Checkstyle. Or in other words, I would not apply the format now, not even for new code, as it would not provide a real benefit but leads to mixed styles.

BTW, I do not like to store any IDE-specific stuff in the repository, as this has nothing to do with the project itself, and the number of IDEs is virtually endless. Having said that, I think the WIKI could be a good place for this.

[arjantijms]

I don't know what others think, but if these settings are close to the current code format used, we could ask @wesleyegberto to create a pull request and start using this format for new code.

Nice, this is what the CDI spec did as well (although they only ever committed the Eclipse formatting file). See https://github.com/cdi-spec/cdi/tree/master/api/src/ide/eclipse

[mkarg]

As @arjantijms 's PR https://github.com/eclipse-ee4j/jaxrs-api/pull/677 shows, a decising for a specific format implies lots of file changed. In the current more or less unclear situation I would like to keep the master free of such mass changes, as it would conflict with other open PRs etc. So my proposal is:

• Let's vote for actually using the EE4J formatting rules (and no other formatting rules discussed earlier).
• Let's shift #677 from target 2.2 to target 3.0 as I proposed above (July 7).
• Let's amend #677 to enforce this formatting.
• Let's amend #677 to reference the actual ruleset.
• Let's reference the actual ruleset in our WIKI.
• Let's put IDE formatting configs in our WIKI.

I appreciate the existing status of preparation, but would be more happy with a calm and coordinated approach. :-)

[chkal]

• Let's vote for actually using the EE4J formatting rules (and no other formatting rules discussed earlier).

I would be fine with applying the EE4J code formatting rules.

BTW: You can find the formatting rules here.

• Let's shift #677 from target 2.2 to target 3.0 as I proposed above (July 7).

I don't think this is a good idea. If we agree on a code format, then we should apply it NOW. Of course we have to find some good time slot for this as it may affect pending pull request, but I'm pretty sure that this is doable.

Also, there is currently no branch for 3.0. And I would like to avoid to create it now. We would have three major branches (master, EE4J_8, 3.0) and waste much time merging changes between them.

I don't really see a downside of applying the new code format now beside the fact that we need some coordination for when to do it.

• Let's amend #677 to enforce this formatting.
• Let's amend #677 to reference the actual ruleset.
• Let's reference the actual ruleset in our WIKI.
• Let's put IDE formatting configs in our WIKI.

Agreed!

[mkarg]

I understand your concerns, and that's why I wanted to format the stuff back in March, when we had only one or two small open PRs. Also I think after 2.2 would be better because 3.0 will imply a lot of huge changes at all, so we could do at as the very first action after merging all open PRs into 2.2 and before accepting any PRs against 3.0. But OK, we could also do it now if it is wanted so urgently. But who is the one that does the reformatting of all open PRs according to the new rules? Volunteers, please! ;-)

BTW, in fact you wouldn't have any trouble with merging between branches. I will do that, just as I mainted EE4J_8 and rollups all the time anyways. In fact, if we would have followed my proposed branching model, this would have spared me a lot of time, because manually cherry-picking the rollups was no fun, too, really. Having said that, as it would be me who maintains the 3.0 job, just as it was me who had the work with EE4J and the rollups, I do not see your argument here. It makes my job easier and it implies no additional work to you. Anyways, this is off-topic, as we just wanted to talk about formatting here. :-)

Back to formatting, now that you posted the link: I think it would be a good idea to have formatting ruleset files not put in our WIKI but in the EE4J wiki, just aside the ruleset.

[chkal]

I understand your concerns, and that's why I wanted to format the stuff _back in March_, when we had only one or two small open PRs.

I agree. That's why we started the first discussions very early. However, that was even before the EE4J formatting rules existed.

But OK, we could also do it now if it is wanted so urgently.

I think applying the new rules as soon as we agreed on them is a good thing. Otherwise we would work many many month with the old rules and apply them much much later. I don't think that this will work.

How do others feel about that?

But _who_ is the one that does the reformatting of all open PRs according to the new rules? Volunteers, please! ;-)

That's why I was talking about a good "time slot". I'm sure if we agree on such a time slot, we will be able to merge most of the pending PRs before doing the reformatting.

Back to formatting, now that you posted the link: I think it would be a good idea to have formatting ruleset files not put in _our_ WIKI but in the EE4J wiki, just aside the ruleset.

+1

[wesleyegberto]

Hi

I would like to know if anyone has checked the Eclipse settings I'd provided here

As pointed by @chkal, some details may differ between IDE's.

Especially because details of the formatting will always differ between Eclipse, IntelliJ and so on.

So I will setup and export the settings from those IDE's after double check each rule.

If @arjantijms provides his settings, which were used in his PR, I could used it instead of mine.

[arjantijms]

@chkal

I think applying the new rules as soon as we agreed on them is a good thing. Otherwise we would work many many month with the old rules and apply them much much later. I don't think that this will work.

How do others feel about that?

+1 for applying the rules now indeed.

If @arjantijms provides his settings, which were used in his PR, I could used it instead of mine.

Sure, there you go:

ee4j.zip

[mkarg]

@arjantijms thanks for the settings. I will ask the PMC to put them into their wiki.

[wesleyegberto]

I just pushed here an initial setup with @arjantijms settings with a small change to reflect one section from Sun's CC.

The settings available are for Eclipse and IntelliJ, I will configure now for Netbeans.

Here is a diff comparing the formatted code from Eclipse (on the left) and IntellijJ (on the rigth - note that the comments formatting has line wrap with width 80) using it.
To compare with the same class from arjantijms PR, just search for client/Entity.class on files tab.

On the repository there are some points I noted.
Please let me know if there is anything to fix.

[mkarg]

@wesleyegberto I do not understand what you do currently as the discussion came to the current end that we will upload Arjan's changes to the EE4J wiki, which I already initiated. So please send your changes there. Thanks.

[spericas]

@chkal I agree with the use of the EE4J rules for 2.2.

[mkarg]

Arjan's IDE settings are available meanwhile: https://github.com/eclipse-ee4j/ee4j/blob/master/codestyle/ee4j-eclipse-formatting.xml :-)

[mkarg]

@andymc12 @asoldano @jansupol Can you please vote regarding using EE4J formatting, and for what release 2.2 or 3.0 we shall apply it? :-)

[asoldano]

I'm fine with the changes for EE4J rules being applied anytime

[andymc12]

Agreed. I don't have a strong opinion either way.

[mkarg]

Thanks to everybody for participating in this discussion!

As there had been no more contributions in the past few days, and as the discussion was open for two weeks meanwhile, I think we can call the proposal of using EE4J rules to master right now as accepted.

As the assignee of this issue, I want to thank @arjantijms for preparing the Eclipse IDE rules and formatting all the files, and I want to thank @dblevins for uploading it to the EE4J's top level project. The JAX-RS source code formatting still is to be ratified. As a consequence, I now call all committers for voting on PR #677!

I will close this issue now, as it got deprecated by our decision of using the top level project's IDE formatter configs. Having said that, I want to encourage everybody to donate similar configurations for other IDEs to the top level project.