Skip to content

8373186: Improve readability of core reflection toString specifications #28688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jddarcy wants to merge 1 commit into
base: master
Choose a base branch
from
+29 −26
Open

8373186: Improve readability of core reflection toString specifications #28688

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 29 additions & 26 deletions src/java.base/share/classes/java/lang/reflect/Field.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,24 +346,24 @@ public int hashCode() {
}

/**
* Returns a string describing this {@code Field}. The format is
* the access modifiers for the field, if any, followed
* by the field type, followed by a space, followed by
* the fully-qualified name of the class declaring the field,
* followed by a period, followed by the name of the field.
* {@return a string describing this {@code Field}}
Copy link
Contributor

@AlanBateman AlanBateman Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Field::toString has been specified this way since JDK 1.1 and we have to assume there are frameworks or libraries that would break if we were ever change the format of the String representation. Would it be possible to put more context for the proposal in the JBS or PR? I think I'm mostly trying to understand if this is just about readability or whether an incompatible change to the string representation might follow.

Copy link
Member Author

@jddarcy jddarcy Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have any implementation changes planned, but if there are new kinds of things added, I prefer to avoid treating the toString() method as a home for a context free grammar to provide all the necessary information about the item.

Copy link
Contributor

@RogerRiggs RogerRiggs Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see a compelling reason to backtrack on the format of toString.
Its likely to break some application or description of the field to a user.

Copy link
Member

@liach liach Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the reason to change the format is some future modifiers, like ACC_STRICT_INIT, won't get printed.

Copy link
Member Author

@jddarcy jddarcy Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, it helps avoid "attractive nuisance" questions like "how does the toString() of a bridge method indicate it is a bridge method"? (There is no such indication in the toString output, other than indirectly via the return type, but there is a Method.isBridge() predicate.)

*
* The string includes information about access modifiers of the
* field, the type of the field, the type declaring the field,
* and the name of the field.
*
* For example:
* <pre>
* public static final int java.lang.Thread.MIN_PRIORITY
* private int java.io.FileDescriptor.fd
* public static java.util.List Foo.bar
* </pre>
Copy link
Member

@liach liach Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having such examples here means this method has a specified output that users can parse. We should move this to some non-normative section like an implementation note.

(Don't know why github mobile didn't capture my comment before, I already commented yesterday)

Copy link
Member Author

@jddarcy jddarcy Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. it is possible to move the examples so they are more clearly informative rather than normative.

As a counterpoint, the toString() spec for java.lang.annotation.Annotation states:

Returns a string representation of this annotation. The details of the representation are implementation-dependent, but the following may be regarded as typical:

@com.example.Name(first="Duke", middle="of", last="Java")

Developers used this string successfully for informative purposes, even though the exact details have been changed (improved and corrected) a number of times over the years.

*
* <p>The modifiers are placed in canonical order as specified by
* "The Java Language Specification". This is {@code public},
* {@code protected} or {@code private} first, and then other
* modifiers in the following order: {@code static}, {@code final},
* {@code transient}, {@code volatile}.
* @apiNote
* Specific information about {@linkplain #getModifiers()
* modifiers} or other aspects of the field should be retrieved
* using methods for that purpose.
Comment on lines +362 to +365
Copy link
Contributor

@RogerRiggs RogerRiggs Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is needlessly vague and gives an opportunity to reinforce the preferred order of modifiers.

*
* @return a string describing this {@code Field}
* @jls 8.3.1 Field Modifiers
*/
public String toString() {
Expand All @@ -380,21 +380,24 @@ String toShortString() {
}

/**
* Returns a string describing this {@code Field}, including
* its generic type. The format is the access modifiers for the
* field, if any, followed by the generic field type, followed by
* a space, followed by the fully-qualified name of the class
* declaring the field, followed by a period, followed by the name
* of the field.
*
* <p>The modifiers are placed in canonical order as specified by
* "The Java Language Specification". This is {@code public},
* {@code protected} or {@code private} first, and then other
* modifiers in the following order: {@code static}, {@code final},
* {@code transient}, {@code volatile}.
*
* @return a string describing this {@code Field}, including
* its generic type
* {@return a string describing this {@code Field}, including
* its generic type}
*
* The string includes information about access modifiers of the
* field, the type of the field, the type declaring the field,
* and the name of the field.
*
* For example:
* <pre>
* public static final int java.lang.Thread.MIN_PRIORITY
* private int java.io.FileDescriptor.fd
* public static java.util.List&lt;java.lang.String&gt; Foo.bar
* </pre>
*
* @apiNote
* Specific information about {@linkplain #getModifiers()
* modifiers} or other aspects of the field should be retrieved
* using methods for that purpose.
*
* @since 1.5
* @jls 8.3.1 Field Modifiers
Expand Down