What is the difference between `Enum.name()` and `Enum.toString()`?

After reading the documentation of String java.lang.Enum.name() I am not sure I understand when to use name() and when to use toString().

> Returns the name of this enum constant, exactly as declared in its enum declaration. Most programmers should use the toString method in preference to this one, as the toString method may return a more user-friendly name. This method is designed primarily for use in specialized situations where correctness depends on getting the exact name, which will not vary from release to release.

In particular, even though the documentation says to prefer toString(), Java's own StandardLocation enumeration uses name when I would have thought the documentation suggested otherwise.

public String getName() { return name(); }

Furthermore Enum implements toString() as,

public String toString() {
    return name;
}

and I cannot think of a situation where a user defined enumeration would overwrite toString() so name() and toString() are almost always exactly the same.

1. Can you please explain why ignoring the documentation and always using name() is a bad idea?
2. What about the phrase "will not vary from release to release". If name will not vary, does it imply that java.lang.Enum.toString() would?

The main difference between name() and toString() is that name() is a final method, so it cannot be overridden. The toString() method returns the same value that name() does by default, but toString() can be overridden by subclasses of Enum.

Therefore, if you need the name of the field itself, use name(). If you need a string representation of the value of the field, use toString().

For instance:

public enum WeekDay {
    MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY;

    public String toString() {
        return name().charAt(0) + name().substring(1).toLowerCase();
    }
}

In this example, WeekDay.MONDAY.name() returns "MONDAY", and WeekDay.MONDAY.toString() returns "Monday".

WeekDay.valueOf(WeekDay.MONDAY.name()) returns WeekDay.MONDAY, but WeekDay.valueOf(WeekDay.MONDAY.toString()) throws an IllegalArgumentException.

Use toString() when you want to present information to a user (including a developer looking at a log). Never rely in your code on toString() giving a specific value. Never test it against a specific string. If your code breaks when someone correctly changes the toString() return, then it was already broken.

If you need to get the exact name used to declare the enum constant, you should use name() as toString may have been overridden.

Use toString when you need to display the name to the user.

Use name when you need the name for your program itself, e.g. to identify and differentiate between different enum values.