How to turn off the Eclipse code formatter for certain sections of Java code?

Question

I've got some Java code with SQL statements written as Java strings (please no OR/M flamewars, the embedded SQL is what it is - not my decision).

I've broken the SQL statements semantically into several concatenated strings over several lines of code for ease of maintenance. So instead of something like:

String query = "SELECT FOO, BAR, BAZ FROM ABC WHERE BAR > 4";

I have something like:

String query =
    "SELECT FOO, BAR, BAZ" +
    "  FROM ABC          " +
    " WHERE BAR > 4      ";

This style makes the SQL much easier to read and maintain (IMHO), especially for larger queries. For example, I can put my editor into "overwrite" mode and modify the text in-place fairly easily.

Note that this issue generalizes beyond the particular example of SQL. Any code that is written with any vertical formatting, particularly tabular constructs, is susceptible to destruction by a pretty printer.

Now, some project members use the Eclipse editor and the semantic formatting is often destroyed when they format an entire source file.

Is there a way to instruct Eclipse to ignore certain lines of source with respect to formatting?

I'm looking for something like a special comment that toggles the Eclipse formatter. Ideally, such a comment could be configurable to be whatever we choose, and other formatters could be programmed to respect it as well:

// STOP-ECLIPSE-FORMATTING
String query =
    "SELECT FOO, BAR, BAZ" +
    "  FROM ABC          " +
    " WHERE BAR > 4      ";
// START-ECLIPSE-FORMATTING

Obviously, one "solution" is to have our team members standardize on some external formatter like Jalopy or JIndent, but that's not what this question is about (also, not my decision on this project): I'm specifically looking for a way to avoid the Eclipse formatter on an ad-hoc basis.

Ideally, a solution will allow me to insert instructions for the Eclipse formatter without requiring team members using Eclipse to do any IDE reconfiguration (other than possibly choosing a formatter agnostic command comment: STOP-ECLIPSE-FORMATTING → STOP-FORMATTING).

Emia

We've had this problem. Eclipse should have an option to always break a line in a String constructor where a + is, regardless of whether the next bit of string would fit on the line. But it doesn't. :-( – Weakfish

Apparently this feature was added in Eclipse 3.6M6: bugs.eclipse.org/bugs/show_bug.cgi?id=27079 – Anglice

Note: If you simply want to prevent eclipse from messing up your comments, then you can use // in front of each line. To comment out a block, highlight and press Ctrl+/. – Tetraploid

Note that now 10 years later, Java 14 will probably bring multi-line strings making this a thing of the past. – Character

Text blocks have been available since Java 15, and is suitable for SQL queries like this. See openjdk.java.net/jeps/378 – Clachan

Answer 1

Eclipse 3.6 allows you to turn off formatting by placing a special comment, like

// @formatter:off
...
// @formatter:on

The on/off features have to be turned "on" in Eclipse preferences: Java > Code Style > Formatter. Click on Edit, Off/On Tags, enable Enable Off/On tags.

It's also possible to change the magic strings in the preferences — check out the Eclipse 3.6 docs here.

More Information

Java > Code Style > Formatter > Edit > Off/On Tags

This preference allows you to define one tag to disable and one tag to enable the formatter (see the Off/On Tags tab in your formatter profile):

You also need to enable the flags from Java Formatting

Suspicious

The "Never join lines" option that is mentioned elsewhere in this page is also very useful. – Suspicious

The on/off features have to be turned "on". In Eclipse preferences: Java > Code Style > Formatter. Click on "Edit" button, "Off/On Tags", check off "Enable Off/On tags". – Homeopathist

This isn't available in JavaScript Code Style preferences, where I have the exact opposite problem with formatting. :( – Recline

Teams should export a copy of Eclipse prefs (file) to their wiki and require everyone to use the same one. Works well for us. ;) – Viewable

FYI I had to remove the space between the // and the @ sign to get this to work. – Ufo

Is there any hotkey for this? – Odom

@theGamblerRises: u can define a template that explands to the respective strings. i have done this myself and use foff and fon for this. – Algometer

Thank you very much! This also works when using maven-formatter-plugin (I changed setting org.eclipse.jdt.core.formatter.use_on_off_tags manually in the formatter xml file). – Roadrunner

Answer 2

AFAIK from Eclipse 3.5 M4 on the formatter has an option "Never Join Lines" which preserves user lines breaks. Maybe that does what you want.

Else there is this ugly hack

String query = //
    "SELECT FOO, BAR, BAZ" + //
    "  FROM ABC"           + //
    " WHERE BAR > 4";

Pish

So in addition to setting the "Never Join Lines" option I also have to write these "phantom" comments? Shouldn't the "Never Join Lines" part work by itself? – Emia

Yes, of course it should. The phantom comments are an alternative approach (in case it doesn't exist, or you're stuck with an earlier version, etc.). – Medwin

I've used this approach in tandem with a custom formatting template in TOAD to allow me to strip the old SQL from JAVA code, reformat it and get all the extraneous comments and then throw it back into JAVA. It's a pain, but it's allowed us to auto-format on save our Java code now. Thanks for the suggestion! – Sluggard

Without checking the "Never join lines" the on/off macros do not work for me - thanks! – Lefebvre

Answer 3

See this answer on SO.

There is another solution that you can use to suppress the formatting of specific block comments. Use /*- (note the hyphen) at the beginning of the block comment, and the formatting won't be affected if you format the rest of the file.

/*-
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 *    one
 *        two
 *            three
 */

Source: Documentation at Oracle.

Aptitude

This is the best answer since it does not depend on the configuration of the user's IDE. Thanks. – Tropicalize

Answer 4

Instead of turning the formatting off, you can configure it not to join already wrapped lines. Similar to Jitter's response, here's for Eclipse STS:

Properties → Java Code Style → Formatter → Enable project specific settings OR Configure Workspace Settings → Edit → Line Wrapping (tab) → check "Never join already wrapped lines"

Save, apply.

Fricandeau

I think this would help for things like the SQL example, but I'm not sure that it would be sufficient for the general case of completely disabling the IDE formatter. – Emia

This solution is excellent when using the builder pattern and its relevance is certainly increased with the introduction of lambdas in Java 8. – Torchwood

This also works well formatting java stream functions like map->filter->reduce. – Trilemma

Answer 5

You have to turn on the ability to add the formatter tags. In the menubar go to:

Windows → Preferences Java → Code Style → Formatter

Press the Edit button. Choose the last tab. Notice the On/Off box and enable them with a checkbox.

Fluellen

Answer 6

If you put the plus sign on the beginning of the line, it formats differently:

String query = 
    "SELECT FOO, BAR, BAZ" 
    +    "  FROM ABC"           
    +    " WHERE BAR > 4";

Influence

This might be an interesting compromise. In general, I'd like to refrain from changing the formatting of the code too much due to some undesirable behavior of one tool. In this case, the string concatenation operators are more of an accident rather than the essence of what's going on with the SQL. That's why I prefer to write them at the end of each line. I feel that the SQL should be emphasized as the beginning of the line. But this may be a good way to go in the absence of a solution that lets me preserve my desired formatting. Thanks! – Emia

You're welcome. Actually, I've been putting my + signs at the front of lines for decades, and not to fool the formatter. I prefer them at the front, because it makes what's happening clearer to me: what's at the end of a line sometimes gets lost. It was the project standard someplace way back when we used woodburning compilers, and it's stuck with me. – Influence

Answer 7

End each of the lines with a double slash "//". That will keep eclipse from moving them all onto the same line.

Benilda

Answer 8

I'm using fixed width string-parts (padded with whitespace) to avoid having the formatter mess up my SQL string indentation. This gives you mixed results, and won't work where whitespace is not ignored as it is in SQL, but can be helpful.

    final String sql = "SELECT v.value FROM properties p               "
            + "JOIN property_values v ON p.property_id = v.property_id "
            + "WHERE p.product_id = ?                                  "
            + "AND v.value        IS NOT NULL                          ";

Anticlinal

Answer 9

Alternative method: In Eclipse 3.6, under "Line Wrapping" then "General Settings" there is an option to "Never join already wrapped lines." This means the formatter will wrap long lines but not undo any wrapping you already have.

Gauss

Answer 10

@xpmatteo has the answer to disabling portions of code, but in addition to this, the default eclipse settings should be set to only format edited lines of code instead of the whole file.

Preferences->Java->Editor->Save Actions->Format Source Code->Format Edited Lines

This would have prevented it from happening in the first place since your coworkers are reformatting code they didn't actually change. This is a good practice to prevent mishaps that render diff on your source control useless (when an entire file is reformatted because of minor format setting differences).

It would also prevent the reformatting if the on/off tags option was turned off.

Plage

Answer 11

The phantom comments, adding // where you want new lines, are great!

1. The @formatter: off adds a reference from the code to the editor. The code should, in my opinion, never have such references.

2. The phantom comments (//) will work regardless of the formatting tool used. Regardless of Eclipse or InteliJ or whatever editor you use. This even works with the very nice Google Java Format

3. The phantom comments (//) will work all over your application. If you also have Javascript and perhaps use something like JSBeautifier. You can have similar code style also in the Javascript.

4. Actually, you probably DO want formatting right? You want to remove mixed tab/space and trailing spaces. You want to indent the lines according to the code standard. What you DONT want is a long line. That, and only that, is what the phantom comment gives you!

Pastore

Answer 12

In VS Code

Set the below property in you formatter xml settings

<setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="true"/>

Then in your Code use the below tags to switch on and off formatting

            // @formatter:off
            //Create Payment Transaction
            payTxn = EN_PaymntTxn.builder()
                    .orderId(paymReq.getOrderId())
                    .paymentMode(paymReq.getPaymentMode())
                    .amount(paymReq.getAmount())
                    .paymentStatus("PAID")
                    .referenceNumber(UUID.randomUUID().toString())
                    .timestamp(Instant.now())
                    .build();
            // @formatter:on

Squeal

Answer 13

Not so pretty but works with default settings and for the first line as well:

String query = "" +
    "SELECT FOO, BAR, BAZ" +
    "  FROM ABC          " +
    " WHERE BAR > 4      ";

Lacerate

Answer 14

This hack works:

String x = "s" + //Formatter Hack
    "a" + //
    "c" + //
    "d";

I would suggest not to use the formatter. Bad code should look bad not artificially good. Good code takes time. You cannot cheat on quality. Formatting is part of source code quality.

Issue

Not using the formatter is just a bad idea; the formatter helps to catch errors and keeps the code in a consistent state. – Jerky

An interesting suggestion, but I don't see how formatting tells us whether code is good or not. – Medwin

I think what he's saying is that he feels that poorly written, poorly formatted code should be kept as-is rather than formatting it in the hope of "improving it." Poorly written, poorly formatted code should "stick out" somehow so that it can be easily identified. Not quite sure that I totally agree, but I think that's the idea. – Emia

@Francis - Bugs: How can auto-formatted code finding bugs? Consistency: Consistency is a nice argument but overall code quality is more important. You can define a nice consistent process for hamburger flipping but it will never work for haute cuisine. Cooking a can be a reasonably complicated activity or trivial if you ignore enough facts. If you think that software development is like hamburger flipping tools enforcing consistency are for you. This is not an argument against formatting guide lines but if the developers don't care about these guidelines the won't care about other essentials. – Issue

My argument here: I write good code and I stick to the formatting guide lines. But I am LAZY. Why should I have to insert the correct amount of spaces and line breaks when I can write my five lines of sloppy code, press the format-button and be happy? AFTER I have formatted the code, using my tool that makes sure the result is always perfect, I am as nazi as anyone about the formatting. There is NO argument against sticking to the guide lines (other that that they may be particularly bad) if the formatting is just a kestroke away. All project members share the same code formatting settings. – Bunin

LOL, I disagree but it's funny. – Owsley

This is completely misunderstanding the "Bad code should look not look good"-argument: Quite the opposite, a cleanly and consistently formatted source will help you see "code smells" much faster, as your internal parser can kick in and see "but that thing looks way to complicated!", or simply "that looks strange?". – Avunculate

I completely agree with not using automatic formatting.It isn't hard to format code properly, and the autoformatter always ends up breaking things that a proper developer would have formatted in a certain way to improve readability. The sheer amount of "how to stop autoformat from doing x?" questions should be proof enough of this. No machine can be better than someone who cares about what they're doing, and if someone doesn't care enough to put in a stupid tab they're likely ignoring much more important underlying issues and I'd rather they weren't messing with my codebase at all. – Catachresis