Description Philippe Verdy 2007-10-31 16:12:46 EDT

Build ID: 3.1.0

Steps To Reproduce:
Currently, the formater breaks single line comments into multiple ones when indenting the code like this:

   <---- MARGINS ---->
   some code; // some long comment...
   <---- MARGINS ---->

which can easily become:

   <---- MARGINS ---->
   some code; // some
       // long
       // comment...
   <---- MARGINS ---->

This is really bad: single line comments should not be broken this way, notably because:
* (1) it is not logical: single line comments that are only following spaces are about the code AFTER the comment, but single line comments that occur after everything else on the same line are about the code BEFORE the comment.

* (2) this is not reversible (when changing the indentation level, and this makes the comment nearly unusable and taking too much space, and most of these comments are not full sentences, so it's impossible to determine if this continues the single-line comment started on the previous line, or if this starts a new comment for the next line.

One solution would be to decide that every single line comment that occurs without leading content before them on the same line is implicity continuing the single-line comment occuring on the previous line, unless there's a blank line between them. Then if you must linewrap a single-line comment, ensure that it is followed by at least a blank line. And generally, all groups of single line-comments that occur on lines with just indenation spaces, should be formated by ensuring that they are preceded by a blank line. Like this:

   <---- MARGINS ---->
   
   // some long
   // comment...
   some code;
   <---- MARGINS ---->

(there's a forced blank line before the line-wrapped single line comments block.)

Single line comments should better be converted into multiline comments on the previous line, like this, if line wrap must be performed:

   <---- MARGINS ---->
   /* some long
    * comment... */
   some code;
   <---- MARGINS ---->

Finally, when wrapping multiline comments (separately from  Javadoc), there should be an option to remove the leading and terminal wrap of the comment, when this is not needed. The example just aboves is currently reformated needlessly as:

   <---- MARGINS ---->
   /*
    * some long
    * comment...
    */
   some code;
   <---- MARGINS ---->


And there should even be an option to convert all possible multiline comments into single line comments on the following line (if they fit), or the reverse option (converting all single line comments to multiline comments on the previous line)

With these settings, the useful "Format" option would maintain readability and meaning of the comments in sources.


More information: