Thanks again, Andrea, for your massive effort. This is really great. I think the Google AOSP option does a good job and is the only one I could stomach. As you note, it also has automated tooling for reduced implementation effort. I have added my vote to the Doodle poll.
Perhaps you could send a separate email to draw attention to the poll? This poll is an important change and merits attention.
Some detailed observations on Google AOSP:
tl;dr: aggressive Javadoc reformatting, aggressive operator and argument line breaks, ignoring @formatter:off introduces some loss of indentation of hand-formatted inline XML (for example) as expected
For the convenience of readers, GitHub compare before/after (limited to 3000 files per diff):
https://github.com/aaime/geotools/compare/04c24bd...aaime:aosp_format
https://github.com/aaime/geowebcache/compare/e21ecaa...aaime:aosp_format
https://github.com/aaime/geoserver/compare/2d7d842...aaime:aosp_format
Javadocs are reformatted aggressively:
- One line javadocs with /** ... */ spread over three lines are converted to a single /** ... */ line
- Paragraphs in javadocs get a <p> tag
- Trailing closing tags like </li> are removed (making it HTML not XHTML)
The formatter introduces aggressive line breaks for multiple operators like "+" to concatenate strings. This is a good thing and makes my use of trailing "//" comments and later @formatter:off mostly redundant. The Google AOSP formatter seems much more keen than Eclipse to break long argument lists over multiple lines. This uses a lot of vertical space but improves legibility. I would have done this before but Eclipse formatting wore me down! You can see many of these changes in gs-app-schema-test FeatureChainingWfsTest:
https://github.com/aaime/geoserver/compare/2d7d842...aaime:aosp_format#diff-a6b0798578a6d274c63757511288f27eR649
Hand-indented concatenated strings (containing XML) protected with @formatter:off lose their indentation because @formatter:off is ignored, so nested elements become a flat list. Here is an example from gs-wps-core:
Before: https://github.com/aaime/geoserver/blob/7cd240f/src/extension/wps/wps-core/src/test/java/org/geoserver/wps/ExecuteTest.java#L203
After: https://github.com/aaime/geoserver/blob/aosp_format/src/extension/wps/wps-core/src/test/java/org/geoserver/wps/ExecuteTest.java#L207
Indentation internal to string literals is preserved and still looks fine. This example as before from gs-app-schema-test FeatureChainingWfsTest. I do not know if my trailing "//" comments help:
https://github.com/aaime/geoserver/compare/2d7d842...aaime:aosp_format#diff-a6b0798578a6d274c63757511288f27eR1506
This spot where I used @formatter:off to stop Eclipse from putting constants on the same line is just as good after Google AOSP with @formatter:off ignored! This is likely because of aggressive line breaking in Google AOSP:
Before: https://github.com/aaime/geotools/blob/04c24bdd0e26e2a8ce24423ce918cfca0130a027/modules/library/referencing/src/main/java/org/geotools/referencing/operation/projection/AzimuthalEquidistant.java#L434
After: https://github.com/aaime/geotools/blob/53c981136892efd7f895c0e93fcc045e7637880e/modules/library/referencing/src/main/java/org/geotools/referencing/operation/projection/AzimuthalEquidistant.java#L432
Grepping the code base for "@formatter" might help locate spots that need work. Trailing "//" comments and space internal to string literals might be an acceptable alternative.
Kind regards,
Ben.
On 25/03/18 22:20, Andrea Aime wrote:
Hi,
I have setup a few branches for people to check the mass reformat attempt
using AOSP style
(and for GeoTools, also Google style).
Please take five minutes to review the Google style guide:
https://google.github.io/styleguide/javaguide.html
The AOSP format is like the Google one, but indents 4 spaces and has
continuation indents at 8 spaces (while Google does 2 and 4 respectively).
And then check the branches (look at files that you edit often and are
familiar with).
AOSP convention (has maven tools to format and enforce):
- https://github.com/aaime/geotools/tree/aosp_format
- https://github.com/aaime/geoserver/tree/aosp_format
- https://github.com/aaime/geowebcache/tree/aosp_format
Google style convention (has maven tools to format and enforce):
- https://github.com/aaime/geotools/tree/google_format
Plain IntelliJ reformat (this one will have no support for build checks,
will rot over time, unless we invest a lot of time to do a manual
post-reformat that satisifies CheckStyle too):
- https://github.com/aaime/geotools/tree/intellij_format
I did setup a Doodle for people to express an opinion on the various
options, please cast your votes (try to vote anything
you can stomach, not just your preferred option):
https://doodle.com/poll/gchp96ka93g5r7ek
I know formatting is a difficult topic, it has been causing troubles with
pull request (we're asking people to
follow rules that are not respected in the existing code) and indeed there
is a number of files looking like s***t.
However, I'm doing this for the benefit of the project and don't want to be
flamed to a crisp two week down the
line because people did not care to check before.
If there is not enough participation to the Doodle or there is no
reasonable agreement I'll simply give up the attempt
and leave the code as is.
Cheers
Andrea
==
GeoServer Professional Services from the experts! Visit http://goo.gl/it488V
for more information.
Ing. Andrea Aime
@geowolf
Technical Lead
GeoSolutions S.A.S.
Via di Montramito 3/A
55054 Massarosa (LU)
phone: +39 0584 962313
fax: +39 0584 1660272
mob: +39 339 8844549
http://www.geo-solutions.it
http://twitter.com/geosolutions_it
AVVERTENZE AI SENSI DEL D.Lgs. 196/2003
Le informazioni contenute in questo messaggio di posta elettronica e/o
nel/i file/s allegato/i sono da considerarsi strettamente riservate. Il
loro utilizzo è consentito esclusivamente al destinatario del messaggio,
per le finalità indicate nel messaggio stesso. Qualora riceviate questo
messaggio senza esserne il destinatario, Vi preghiamo cortesemente di
darcene notizia via e-mail e di procedere alla distruzione del messaggio
stesso, cancellandolo dal Vostro sistema. Conservare il messaggio stesso,
divulgarlo anche in parte, distribuirlo ad altri soggetti, copiarlo, od
utilizzarlo per finalità diverse, costituisce comportamento contrario ai
principi dettati dal D.Lgs. 196/2003.
The information in this message and/or attachments, is intended solely for
the attention and use of the named addressee(s) and may be confidential or
proprietary in nature or covered by the provisions of privacy act
(Legislative Decree June, 30 2003, no.196 - Italy's New Data Protection
Code).Any use not in accord with its purpose, any disclosure, reproduction,
copying, distribution, or either dissemination, either whole or partial, is
strictly forbidden except previous formal approval of the named
addressee(s). If you are not the intended recipient, please contact
immediately the sender by telephone, fax or e-mail and delete the
information in this message that has been received in error. The sender
does not give any warranty or accept liability as the content, accuracy or
completeness of sent messages and accepts no responsibility for changes
made after they were sent or for other risks which arise as a result of
e-mail transmission, viruses, etc.
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
GeoTools-Devel mailing list
GeoTools-Devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geotools-devel
--
Ben Caradoc-Davies <ben@anonymised.com>
Director
Transient Software Limited <https://transient.nz/>
New Zealand