Making Eclipse's Java code formatter ignore block comments

Question

Is there a way to make Eclipse's built-in Java code formatter ignore comments? Whenever I run it, it turns this:

    /*
     * PSEUDOCODE
     * Read in user's string/paragraph
     * 
     * Three cases are possible
     * Case 1: foobar
     *         do case 1 things
     * Case 2: fred hacker
     *         do case 2 things
     * Case 3: cowboyneal
     *         do case 3 things
     *         
     * In all cases, do some other thing
     */

into this:

    /*
     * PSEUDOCODE Read in user's string/paragraph
     * 
     * Three cases are possible Case 1: foobar do case 1 things Case 2: fred
     * hacker do case 2 things Case 3: cowboyneal do case 3 things
     * 
     * In all cases, do some other thing
     */

I have already played around with the Windows > Preferences > Java > Code Style > Formatter settings but can't find one for keeping comment formatting. I'm using Eclipse 3.4.0.

It's right there in the Formatter config, I don't know how you're missing it. Edit the profile, there's a dialog box with 8 tabs, the last tab is for comment formatting. — skaffman, Jun 21 '09 at 23:16
I do see the comment tab, but the formatting problems happen no matter what combination of checkboxes I use. — Pops, Jun 25 '09 at 01:42
possible duplicate of [How to turn off the Eclipse code formatter for certain sections of Java code?](http://stackoverflow.com/questions/1820908/how-to-turn-off-the-eclipse-code-formatter-for-certain-sections-of-java-code) — user2664856, Dec 04 '13 at 16:42
I'm having the same problem with Scala in Eclipse, but the solutions below are Java-specific, as the Scala code formatter tab has different options. Is there a way to turn off comment-reformatting for Scala? — Glenn Strycker, Oct 31 '14 at 18:52

score 194 · Answer 1 · edited Aug 20 '15 at 05:53

194

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: http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html#350

edited Aug 20 '15 at 05:53

Afriza N. Arief

7,696
5
47
74

answered Mar 28 '11 at 23:19

Michelle Crane

2,841
3
16
4

Never seen that before, even out of context. +1! – Pops Mar 29 '11 at 02:19
18

Sadly, this only works with "regular" block comments, not Javadoc comments. – Pops Jan 11 '12 at 03:19
Perfect for Version: Juno Service Release 1. Thank you, my savior! – Hong Mar 20 '13 at 20:00
1

and even this is useful when you have your own formatter which is appending stars for each line start and you dont want default formatter to do it then you could use /*- ...... */ which is very useful – Shiva Komuravelly Jun 17 '13 at 08:49
Still works in 2020 (Version: 2020-06 (4.16.0)) :-) very nice – rustyx Sep 06 '20 at 15:34

VonC · Accepted Answer · 2018-01-23T12:35:25.900

Update 2010, as pointed by the OP and in this answer, the special string // @formatter:off in Eclipse 3.6 is enough.

It was not available at the time of the question.

Original answer: June 2009, Eclipse 3.4/3.5

With the Java Formatter (Windows > Preferences > Java > Code Style > Formatter), you can create a new Formatter profile.

In the Comments tab (in eclipse3.5), you can make sure, in the "Javadoc comment settings", to uncheck "Format HTML tags".
Check also the "Never join lines" in the "General settings" section.

Then your comment should be written as:

/**
 * PSEUDOCODE
 * Read in user's string/paragraph
 * 
 * Three cases are possible:
 * <dl>
 *   <dt>Case 1: foobar</dt>
 *     <dd>        do case 1 things</dd>
 *   <dt>Case 2: fred hacker</dt>
 *     <dd>        do case 2 things</dd>
 *   <dt>Case 3: cowboyneal</dt>
 *     <dd>        do case 3 things</dd>
 * </dl>        
 * In all cases, do some other thing
 */

Note: I have made a Javadoc comment, and not a simple comment, as I believe a comment with that much text in it may be better placed in front of a method. Plus, Javadoc sections have more formatting parameters to play with.
If it is in front of a method (true Javadoc), the HTML tags <dl>, <dt> and <dd> will help to present it properly within the Javadoc view.

The relevant part of this answer, for me, was that the HTML tags are NOT automatically inserted at line breaks and the like. Probably obvious to most, but I didn't realize I had to hand-code things like
s until I saw it here. — Pops, Jan 12 '10 at 16:00
@Lord Torgamus: not only you have to add thosetags, but the first sentence requires a periode and a space, before the `
`! (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4165985) — VonC, Jan 12 '10 at 16:14
I'm having the same problem with Scala in Eclipse, but the solutions below are Java-specific, as the Scala code formatter tab has different options. Is there a way to turn off comment-reformatting for Scala? — Glenn Strycker, Oct 31 '14 at 18:51

score 29 · Answer 3 · edited May 23 '17 at 11:47

I just learned from a co-worker that Eclipse offers special formatting tags that can be used for this:

// @formatter:off
/*
 * ╔════════╦═══════╦══════════╗
 * ║ Month  ║ Sales ║ Position ║
 * ╠════════╬═══════╬══════════╣
 * ║ June   ║ 44k   ║ 2nd      ║
 * ║ July   ║ 39k   ║ 2nd      ║
 * ║ August ║ 49k   ║ 4th      ║
 * ╚════════╩═══════╩══════════╝
 *
 * This comment shouldn't be formatted, and will now be ignored by the formatter.
 */
// @formatter:on

Note that you may need to manually enable this feature through the Preferences menu → Java > Code Style > Formatter, clicking on Edit, selecting the Off/On Tags tab and checking Enable Off/On tags (source).

A quick Google for the string @formatter:off brought me to this other SO answer, which mentioned this feature in the context of disabling the formatter for code blocks. I've confirmed that it works for line comments, "normal" block comments and Javadoc block comments as well.

How did you make it work for JavaDoc comments? I've found I had to put line comments before and after the JavaDoc comments for this to work, like you did for the block comment in this answer. I was hoping I could turn off formatting just for a section of a JavaDoc comment. — Michael Scheper, Feb 18 '13 at 04:01
@MichaelScheper it's been a while, and I don't remember exactly... did you try [VonC's advice](http://stackoverflow.com/a/1025619/122607)? — Pops, Feb 19 '13 at 15:22
This is excellent, because it tells eclipse to dont format code as well. Useful when you want to keep your own formatting. — Martin Wickman, Mar 05 '14 at 08:32

score 20 · Answer 4 · answered Jan 03 '13 at 14:00

20

Another possibility is to use HTML's <pre> in Javadoc:

/**
 * <pre>
 *    this
 *   is
 *      kept
 *  as
 *    is
 * </pre>
 */

At least this is how I tend to embed my ASCII-art in source code comments :)

answered Jan 03 '13 at 14:00

Thomas Keller

5,933
6
48
80

2
Please note that Eclipse will format contents of
tag if it sees it as a java code (unless you uncheck Window->Preferences->Java->Code Style->Formatter->Edit...[Button]->Comments[Tab]->"Format Java code snippets inside 'pre' tags")
– gswierczynski Aug 05 '14 at 23:32

score 9 · Answer 5 · edited Jan 04 '12 at 16:17

9

Surround the specific text with <pre> </pre> tags.

edited Jan 04 '12 at 16:17

Pops

30,199
37
136
151

answered Feb 10 '10 at 17:57

Philip

99
1
1

score 3 · Answer 6 · answered Jun 16 '19 at 18:17

3

Try this one. This worked for me. With the Java Formatter (Windows > Preferences > Java > Code Style > Formatter), you can create a new Formatter profile from existing and then edit it.

If Eclipse doesn't allow to save this then create a new one and save in that.

answered Jun 16 '19 at 18:17

Milan Kamboya

486
2
11

This is the answer with recent Eclipse : you can now disable any comment formatting (javadoc, block or inline). – Tristan Oct 25 '19 at 09:56

score 2 · Answer 7 · answered Jun 21 '09 at 22:31

2

In Eclipse 3.4: Preferences, Java->Code Style->Formatter, then edit profile, comments tab. There's a bunch of options there for controlling comment formatting.

answered Jun 21 '09 at 22:31

skaffman

398,947
96
818
769

score 2 · Answer 8 · answered Sep 06 '17 at 02:34

2

one workaround is to add pre tag for the comments that you don't want eclipse to format

/**
 * <pre>
 *    this part
 *   is
 *      out of
 *  format
 *    
 * </pre>
 */

answered Sep 06 '17 at 02:34

K.Andy Wang

401
1
3
14

2

True... but I don't see what this adds to what Philip or Thomas Keller already said in their answers years ago. – Pops Sep 07 '17 at 19:57

score 1 · Answer 9 · answered Nov 26 '15 at 11:13

If you want to supress formatting in eclipse, you can always wrap content that is intended to NOT TO BE FORMATED into <pre>UNFORMATTED CONTENT</pre> tag. Javadoc formatter will detect that tag, and leave everything between that tags unformatted.

Pros:

Rest of Javadoc is still formatted
Javadoc's html output will be "unformatted" as well because of pre tags

Cons:

Not seeing one

Jonathan Fingland · Answer 10 · 2009-06-22T06:06:40.653

It is language-dependent.

For example, if working with javascript, you would go to "Window -> Preferences -> Javascript -> Code Style -> Formatter" and then edit the formatter options.

Edit (reflecting changesin OP Questions

For editing java code formatting, go to "Window -> Preferences -> Java -> Code Style -> Formatter"

At the top of the panel you will see

Active Profile:
Eclipse [built-in]

From there you have one button to the right, "Edit", and two below, "New..." and "Import...". I would recommend Editing the existing profile.

In the edit profile dialog, there are a series of tabs along the top. The last tab is "Comments". To completely disable comment formatting, uncheck "Enable Javadoc comment formatting", "Enable block comment formatting", "Enable line comment formatting", and "Enable header comment formatting".

score 0 · Answer 11 · answered Jan 01 '19 at 12:51

0

You can change this in Windows - Preferences - Java - Code Style - Formatter, than click the Edit.. button, find Comments, choose the Never Join Lines.

Then, it should be OK.

answered Jan 01 '19 at 12:51

GH Dev

1

Making Eclipse's Java code formatter ignore block comments

11 Answers11

Linked

Related