References to google-styleguide in formatter documentation

[fvclaus]

Problem

The official documentation page about linting has a section about formatting which includes a link to the unmaintened/abandoned google/styleguide repo which might be misleading to some unfamiliar with the differences between google/styleguide and google-java-format.

A bit more explanation

The project, I currently work on uses the Intellij google-java-format plugin (like almost any other project, I have worked on in the past 6+ years). I know that the section above links to google/styleguide repo, which is not the same as google/google-java-format repo. Not being overly familiar with the repos, I thought that the formatting output should be the same (or at least very similiar), especially, because the offical documentation links to it.

After spending a few hours trying to get a working solution, it seems to me, that the google/styleguide java style is abandoned (last updated 5 years ago), without an offical statement. I found this issue which funnily enough also mentions the vscode-java docs.

The formatting output is very different. Here is a small example:

google/styleguide:

google/google-java-format:

Suggestion

Can the reference to the google styleguide be removed? I think it would be bad idea to just mention that the formatter is unmaintained, because people don't read carefully enough, instead just copy the configuration.

I know the referenced documentation is not part of this repo, but I (as somebody unaffiliated with vscode-java) didn't want to open an issue on the vscode repo straight away.

google-java-format Solution

This stackoverflow question lists different solutions.

There are a lot of plugins that are floating around (mostly forks of one plugin) where I tried a few, but none worked: https://marketplace.visualstudio.com/search?term=google%20java%20format&target=VSCode&category=All%20categories&sortBy=Relevance

[CsCherrYY]

@fvclaus thanks for the detail explainmination. Since google/styleguide has not been maintained for a long time, I'm curious if we can take advantage of google/google-java-format. e.g., showing the link in the vscode java documentation page.

[fvclaus]

@CsCherrYY , afaik the only way to use the google-java-format as of now, is to call the JAR that does the formatting (see this StackOverflow question. This has the downside of being very slow (one java -jar invocation for every file) and will therefore be suitable only for powerful hardware. I wouldn't endorse (mention in the docs) such a solution. It is a workaround at best and would shed a bad light on vscode-java.

My suggestion would be, to not link to a foreign repo (such as google-styleguide) or any other. I would just say that URLs are supported and provide an obvious placeholder link such as https://raw.githubusercontent.com/<github-repo>/eclipse-formatter-settings.xml. I also thought about hosting a formatter settings xml in this repo, but I fail to see its usefulness. Nobody would ever use it to format code and I wouldn't make for a good starting point either.

[CsCherrYY]

@nickzhums any comments?