You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Mark Thomas <ma...@apache.org> on 2023/01/19 16:55:03 UTC
Checkstyle, Javadoc and automatic formatting
Hi all,
Ever since the first CheckStyle rules were added, I have been looking at
the options for using my IDE (Eclipse) to fix the code so it meets the
rules. The results until today have been mixed. Some stuff gets fixed
but other stuff gets broken.
Today, however, I made progress. I think I have a Eclipse Formatter
configuration that would enable us to turn on a number of the rules that
are currently commented out (indentation, operator at end of line, etc)
and auto format the code to fix any issues without messing up too much
other stuff.
I'd like to start testing out the formatter by reformatting files before
I work on them. However, before I do that I was wondering whether we
wanted to format the Javadoc as well - especially given the recent
Javadoc rules added to CheckStyle.
With that in mind, what do folks think about increasing the comment
width from 80 to 120 to match the code?
After that, my thinking is:
- blank line between description and tags (param, return, throws etc)
- blank line between different tag types (separate param, return etc)
Those are the easy ones. There are lots of options for aligning tags.
Personally, I am looking for clarity while still using space efficiently
so I prefer that parameter and throws descriptions don't start on a new
line after a tag.
With a longer permitted line for Javadoc I think we can:
- align descriptions grouped by type
- indent tag descriptions
That would give Javadoc that looks a bit like this but not as condensed
as I have used a much shorter max line length:
/**
* Method description. May be short or long.
*
* @param first The first parameter. For an optimum result, this
* should be an odd number between 0 and 100.
* @param second The second parameter.
*
* @return The result of the foo operation, usually an even number
* within 0 and 1000.
*
* @throws Exception when the foo operation cannot be performed
* for one reason or another.
*/
With the longer line length, I suspect most tag descriptions won't need
to wrap. However, if we are worried about long exception names or
parameter names causing problems we could use:
/**
* Method description. May be short or long.
*
* @param first The first parameter. For an optimum result, this
* should be an odd number between 0 and 100.
* @param second The second parameter.
*
* @return The result of the foo operation, usually an even number
* within 0 and 1000.
*
* @throws Exception when the foo operation cannot be performed
* for one reason or another.
*/
I think I prefer the first but could live with either.
Thoughts?
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Checkstyle, Javadoc and automatic formatting
Posted by Rémy Maucherat <re...@apache.org>.
On Thu, Jan 19, 2023 at 5:56 PM Mark Thomas <ma...@apache.org> wrote:
>
> Hi all,
>
> Ever since the first CheckStyle rules were added, I have been looking at
> the options for using my IDE (Eclipse) to fix the code so it meets the
> rules. The results until today have been mixed. Some stuff gets fixed
> but other stuff gets broken.
>
> Today, however, I made progress. I think I have a Eclipse Formatter
> configuration that would enable us to turn on a number of the rules that
> are currently commented out (indentation, operator at end of line, etc)
> and auto format the code to fix any issues without messing up too much
> other stuff.
>
> I'd like to start testing out the formatter by reformatting files before
> I work on them. However, before I do that I was wondering whether we
> wanted to format the Javadoc as well - especially given the recent
> Javadoc rules added to CheckStyle.
>
> With that in mind, what do folks think about increasing the comment
> width from 80 to 120 to match the code?
>
> After that, my thinking is:
> - blank line between description and tags (param, return, throws etc)
> - blank line between different tag types (separate param, return etc)
>
> Those are the easy ones. There are lots of options for aligning tags.
> Personally, I am looking for clarity while still using space efficiently
> so I prefer that parameter and throws descriptions don't start on a new
> line after a tag.
>
> With a longer permitted line for Javadoc I think we can:
> - align descriptions grouped by type
> - indent tag descriptions
>
> That would give Javadoc that looks a bit like this but not as condensed
> as I have used a much shorter max line length:
>
> /**
> * Method description. May be short or long.
> *
> * @param first The first parameter. For an optimum result, this
> * should be an odd number between 0 and 100.
> * @param second The second parameter.
> *
> * @return The result of the foo operation, usually an even number
> * within 0 and 1000.
> *
> * @throws Exception when the foo operation cannot be performed
> * for one reason or another.
> */
>
> With the longer line length, I suspect most tag descriptions won't need
> to wrap. However, if we are worried about long exception names or
> parameter names causing problems we could use:
>
> /**
> * Method description. May be short or long.
> *
> * @param first The first parameter. For an optimum result, this
> * should be an odd number between 0 and 100.
> * @param second The second parameter.
> *
> * @return The result of the foo operation, usually an even number
> * within 0 and 1000.
> *
> * @throws Exception when the foo operation cannot be performed
> * for one reason or another.
> */
>
> I think I prefer the first but could live with either.
>
> Thoughts?
Ok for the first.
Personally:
- No opinion at all on javadoc formatting.
- Code formatting is important, but the rules in place were more than
enough to satisfy me. So no opinion on going further.
Rémy
>
> Mark
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: dev-help@tomcat.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org