Disable Eclipse formatting for certain sections of code only

Posted on by

In a previous tip, I showed how to automatically format code every time you save in Eclipse or how to manually format by pressing Ctrl+Shift+F. These work great most of the times but sometimes you want to exclude a certain block of code from formatting, often because the formatting turns out unreadable (ie. ugly) for that particular piece of code.

Eclipse allows you to disable formatting for a certain block or section of code by surrounding that code with formatter comments, known as Off/On tags. And you can also make generating those comments around a block of code extremely simple by creating a simple template.

Disable formatting for a piece of code

By default, the Eclipse formatter doesn’t have Off/On tags enabled so you need to perform a once-off step to enable them:

  1. Go to Window > Preferences > Java > Code Style > Formatter.
  2. If your Active profile is a built-in profile (the name will end in [built-in]) then create a new profile by clicking New… and give your profile a name. If you have Open the edit dialog now selected then Eclipse will immediately open the edit dialog and you can skip step 3.
  3. If your Active profile is a custom profile then click Edit… to open the edit dialog.
  4. Go to the Off/On Tags tab and select the Enable Off/On tags checkbox.
  5. Leave the Off and On tags as-is (but you can change them to anything else you prefer later).

This is what the preference dialog should look like:

Eclipse Off/On TagsOnce you have Off/On Tags enabled, just enclose a section of code in the formatter tags, starting with the designated Off tag then ending with the designated On tag. Here’s an example:


System.out.println("This will be formatted");

// @formatter:off
System.out.println("This will NOT be formatted");
Arrays.asList(
	"one",
	"two");
// @formatter:on

System.out.println("code from this point on is formatted again");

Notes:

  • Eclipse disables all formatting once it hits an off tag. If you don’t include an on tag after that, none of the code after the off tag will be formatted so make sure you always match the off/on tags. I’d recommend using a template to generate both tags once-off. See the section below for such a template.
  • If you like, you can add a comment after the off tag explaining why formatting is disabled, eg: // @formatter:off – Looks ugly with auto formatting.
  • This only works for formatting rules and not for other Save Actions such as cleaning up imports and adding Override annotations. If you want to configure those, then see the post on how to enable automatic formatting.

Template to easily generate the Off/On tags

To make life easier, here’s a template that allows you to select a block of code and wrap it in Off/On tags or to just create the tags with an empty block, ready for you to type some code.

Download this template and import it into Eclipse. This template bundle includes:

  • disableformatting: Creates On and Off tags and positions the cursor inside the block so you can start typing. Also allows selection of lines of code that will be wrapped in the On/Off tags.

If you need more help on importing and using templates, check out the tip on how to work with Eclipse templates.

Related tips

Support Eclipse On E

3 thoughts on “Disable Eclipse formatting for certain sections of code only”

  1. Can’t seem to do this for groovy, even though Groovy formatter says it inherits space and break formatting from Java formatter…anything I should be doing differently?

    • I’m not a 100% sure, but I *think* it may be a problem with the Groovy plugin not handling format on save correctly – see GRECLIPSE-1102 and specifically GRECLIPSE-1104. They don’t mention the on/off blocks but I would imagine it’s related.

  2. Really nice tip. It would be nice if that kind of tags would exist on “Organize Imports” and “Clean Up” source options.