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.

Solution 1

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.

Solution 2

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

Solution 3

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.

Solution 4

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 :)

Solution 5

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

View more solutions

Comments

[skaffman]

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.

[Pops]

I do see the comment tab, but the formatting problems happen no matter what combination of checkboxes I use.

[user2664856]

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

[Glenn Strycker]

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?

[Pops]

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 <br>s until I saw it here.

[VonC]

@Lord Torgamus: not only you have to add thosetags, but the first sentence requires a periode and a space, before the <br />! (see bugs.sun.com/bugdatabase/view_bug.do?bug_id=4165985)

[Pops]

Never seen that before, even out of context. +1!

[Pops]

Sadly, this only works with "regular" block comments, not Javadoc comments.

[Michael Scheper]

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.

[Pops]

@MichaelScheper it's been a while, and I don't remember exactly... did you try VonC's advice?

[Hong]

Perfect for Version: Juno Service Release 1. Thank you, my savior!

[Shiva Komuravelly]

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

[Martin Wickman]

This is excellent, because it tells eclipse to dont format code as well. Useful when you want to keep your own formatting.

[gswierczynski]

Please note that Eclipse will format contents of <pre></pre> 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")

[Glenn Strycker]

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?

[Pops]

True... but I don't see what this adds to what Philip or Thomas Keller already said in their answers years ago.

[Enerccio]

this does not answer the question asked

[Tristan]

This is the answer with recent Eclipse : you can now disable any comment formatting (javadoc, block or inline).

[rustyx]

Still works in 2020 (Version: 2020-06 (4.16.0)) :-) very nice