toString

Written Explanation

How toString gets called

toString() returns a String. You rarely call it by hand, because Java calls it for you whenever it needs an object as text:

• System.out.println(obj) prints the text from obj.toString().
• "Opened " + obj (concatenation) uses it for the object side.
• Logging libraries and the debugger use it to show object values.

Because the method lives in Object, every class has it, and a class that does not override it gets the default ClassName@hexNumber. The Java documentation recommends that every class override toString.

Writing one

The signature is exactly public String toString(). Write @Override so a typo becomes a compile error:

class Account {
    private final String number;
    private double balance;
    private final String pin;
    // constructor omitted

    @Override
    public String toString() {
        return "Account[" + number + ", balance=" + balance + "]";
    }
}

The pin field exists but is deliberately not included.

What to include

A useful description answers "what is this, and which one?":

• the class name, so the log line is self-explanatory;
• the key fields, such as an id, number, or the values that define equality;
• short and on one line, since logs are read line by line.

Keep it free of side effects: toString should only build text, not change state, call a database, or throw exceptions. A toString that can fail turns a logging line into a new bug.

What must stay out

Never include in toString:

• passwords, PINs, security answers, tokens, API keys;
• full card numbers or other government or financial identifiers;
• large amounts of data, such as an entire list of transactions (the log will be huge).

When part of a value is useful, mask it: show only the last four digits of a card, for example. Remember that code which prints account for debugging will do it in production too, and logs are copied to many systems. Keeping secrets and personal data out of logs is standard security practice.

Designing the format

Pick one style and use it in every class of a project, so logs look uniform and are easy to search. A common style is ClassName[field=value, field=value]. Some practical points:

• Put fields in a fixed order, the same as the declaration order, so two lines can be compared by eye.
• Keep each description on a single line. A line break inside toString breaks tools that read logs line by line.
• Include the fields that define equality (Lesson 3) first. When two objects look the same in the log, you can tell whether they are "equal" at a glance.
• Do not try to make toString a data format. If another program needs the data, a later module teaches proper formats such as JSON; toString is for people.

Subclasses

A subclass inherits toString and can extend it with super.toString():

class SavingsAccount extends Account {
    private final double rate;
    // constructor omitted
    @Override
    public String toString() {
        return super.toString() + " rate=" + rate;
    }
}

This reuses the parent's text and adds the new field, so each class describes only what it owns.

Printing null

println(null reference) and "x" + nullReference do not throw: the text null appears. But calling nullReference.toString() directly throws NullPointerException. String.valueOf(obj) and Objects.toString(obj) return "null" for a null reference and obj.toString() otherwise.

toString and the debugger

When you stop a program in a debugger, the variables panel usually shows each object with its toString() text next to the name. With the default, you see only Account@4517d9a3 and must open the object to inspect fields one by one. With a good override you can scan a whole list of objects at a glance. The exact appearance depends on your IDE, so check how yours displays objects, but the benefit is the same everywhere.

toString is not equals

Two objects with the same toString text are not necessarily equal, and two equal objects can print differently if you add a field that equals ignores. Never compare objects by comparing their text (a.toString().equals(b.toString())): it is slow, fragile, and it breaks as soon as someone changes the format. Use equals for equality and keep toString for reading.

IDE-generated versions

Most IDEs can generate toString. The menu name and location differ by IDE and version, so look in your IDE's "generate" or "source" actions. A generated version usually lists every field, so always read it and delete anything sensitive.