Hello fellow developers,
Most older tests have the jtreg tags before import statements.
As an example, JList/6462008/bug6462008.java [1] and
JTextArea/4697612/bug4697612.java [2].
When you open such a test in an IDE, the jtreg tags are collapsed along
with the copyright and license header. I find it inconvenient. The jtreg
tags provide important information about the test: its summary, its
keywords, its requirements and possible parameters.
Over the years, I've been asking people [3][4] to move the jtreg tags to
the class declaration.
When the jtreg tags are before the class declaration (below the import
statements), they're not collapsed, which means you see all the jtreg
tags when you open a test file in the IDE without additional navigation
or mouse movements.
There were a couple of discussions around this matter [5][6]. No
decision has been made.
This message is a call for discussion so that we, the client libraries
developers, agree on a common style.
I propose putting the jtreg tags right above the test class declaration:
import javax.swing.JFrame;
/*
* @test
* @bug <bugids>
* @key headful
* @summary <description of the test>
*/
public final class SampleTest {
The comment with jtreg tags immediately precedes the test class
declaration. There's no blank line between the comment and the
declaration. The comment uses a regular block comment syntax with the
single asterisk ‘/*’ (as opposed to a javadoc comment which starts with
double asterisk ‘/**’).
I also propose establishing an order for the tags for consistency [7].
Most tests have a convention, the tags usually appear in the following
order:
@test
@bug
@key
@summary
@library
@build
@run
In addition to that, manual tests do not need ‘@key headful’ because
“all manual tests are assumed to be headful.” [8]
What do you think?
--
Regards,
Alexey
[1]
https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JList/6462008/bug6462008.java#L24-L31
[2]
https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JTextArea/4697612/bug4697612.java#L24-L29
[3] https://github.com/openjdk/jdk/pull/12180#discussion_r1100013426
[4] https://github.com/openjdk/jdk/pull/11940#discussion_r1102835163
[5] https://github.com/openjdk/jdk/pull/16674#discussion_r1402082665
[6] https://github.com/openjdk/jdk/pull/16785#discussion_r1410944165
[7] https://github.com/openjdk/jdk/pull/16785#discussion_r1403301368
[8]
https://github.com/prrace/jdk/blob/91d8ea79d947aa7dad91d8ed550ed34a7d49d885/test/jdk/TEST.ROOT#L27
