[effective java] item 12. toString을 항상 재정의하라

결론

모든 구체 클래스에서 Object의 String을 재정의하자.
단, 상위 클래스에서 이미 알맞게 재정의한 경우는 예외다. 
toString을 재정의한 클래스는 사용하기도 즐겁고 그 클래스를 사용한 시스템을 디버깅하기 쉽게 해준다.
toString은 해당 객체에 관한 명확하고 유용한 정보를 읽기 좋은 형태로 반환해야 한다.
toString의 반환값 포맷을 문서화하는 것은 선택이다. 
AutoValue 프레임워크를 사용하여 자동 생성하는 방법도 있지만, 직접 작성하는 것이 가장 좋고 재정의하지 않는 것보단 좋다. 

 

PhoneNumber 클래스 예제

public final class PhoneNumber {
    private final short areaCode, prefix, lineNum;

    ...

    /**
     * 이 전화번호의 문자열 표현을 반환한다.
     * 이 문자열은 "XXX-YYY-ZZZZ" 형태의 12글자로 구성된다.
     * XXX는 지역 코드, YYY는 프리픽스, ZZZZ는 가입자 번호다.
     * 각각의 대문자는 10진수 숫자 하나를 나타낸다.
     *
     * 전화번호의 각 부분의 값이 너무 작아서 자릿수를 채울 수 없다면,
     * 앞에서부터 0으로 채워나간다. 예컨대 가입자 번호가 123이라면
     * 전화번호의 마지막 네 문자는 "0123"이 된다.
     */
    @Override public String toString() {
        return String.format("%03d-%03d-%04d", areaCode, prefix, lineNum);
    }

    public static void main(String[] args) {
        PhoneNumber jenny = new PhoneNumber(707, 867, 5309);
        System.out.println("제니의 번호: " + jenny);		//제니의 번호: 707-867-5309
    }
}

 

 

설명

Object의 기본 String 메서드는 PhoneNumber@adbbd 처럼 단순히 클래스_이름@16진수로_표시한_해시코드를 반환할 뿐입니다. 

toString의 일반 규약에 따르면 '간결하면서 사람이 읽기 쉬운 형태의 유익한 정보'를 반환해야 합니다.

 

예를 들어, PhoneNumber@adbbd는 간결하고 읽기 쉽다고 볼 수 있지만, 070-864-5309처럼 직접 알려주는 형태가 훨씬 유익한 정보를 담고 있습니다.

따라서, toString 규약은 "모든 하위 클래스에서이 메서드를 재정의하라"고 합니다. 

 

 

재정의함으로써 얻는 이점: 사용하기에 즐겁고, 디버깅이 쉬워진다. 

toString이 자동으로 호출되는 경우

• println, printf
• 문자열 연결 연산자(+)
• assert 구문을 넘길 때
• 디버거가 객체를 출력할 때

 

위와 같은 경우는 프로그래머가 직접 호출하지 않아도 다른 어딘가에서 쓰입니다.    

 

디버깅이 쉬워진다?

예를 들어, 프로그래머가 작성한 객체를 참조하는 컴포넌트에 오류 메시지를 로깅할 때 toString 메서드를 자동으로 호출할 수 있는데,
toString을 제대로 재정의하지 않는다면 쓸모없는 메시지만 로그에 남을 것입니다. 

PhoneNumber용 toString을 제대로 정의했다면 다음 코드만으로 문제를 진단하기에 충분한 메시지를 남길 수 있습니다.

 

System.out.println(phoneNumber + "에 연결할 수 없습니다.");

toString을 재정의했든 아니든 프로그래머는 대부분은 진단 메시지를 이렇게 만들 것입니다. 

하지만 재정의하지 않으면 그다지 쓸모가 없는 메시지가 출력됩니다. 

 

 

인스턴스를 포함하는 객체에서 유용하게 쓰인다 ex) Map

좋은 toString은 (특히 컬렉션처럼) 이 인스턴스를 포함하는 객체에서 유용하게 쓰입니다.

 

예를 들어, map객체를 출력했을 때 {Jenny=PhoneNumber@abddb} 보다는  {Jenny=707-867-5309}라는 메시지가 나오는 게 훨씬 반갑게 느껴집니다. 

 

 

재정의시 주의사항

1. 그 객체가 가진 주요 정보 모두를 반환하는 게 좋습니다.
   
   • 다음 예시는 toString에 주요 정보가 담기지 않았을 때 문제가 되는 대표적인 예입니다.
   • ex) Assertion failure: expected {abc, 123}, but was {abc, 123}.
     // 예상값 {abc, 123}, 실젯값 {abc, 123}
   • 예상값과 실제 실행한 값이 달라 에러가 발생한 것인데, toString에 주요 정보를 포함하지 않아 구별이 되지 않습니다. 
2. 하지만, 객체가 거대하거나 객체의 상태가 문자열로 표현하기에 적합하지 않다면, 요약 정보를 담아야 합니다.
   • ex) "맨해튼 거주자 전화번호부(총 1487536개)", "Thread[main, 5, main]" 
   • 이상적으로는 스스로를 완벽히 설명할 수 있는 문자열이어야 합니다.
     (위의 스레드 예는 이 조건에는 맞지 않습니다.)
3. 마지막으로, toString을 구현할 때면 반환값의 포맷을 문서화할지 정해야 합니다. 

 

toString 반환값 포맷의 문서화

PhoneNumber 클래스 예제

public final class PhoneNumber {
    private final short areaCode, prefix, lineNum;

    ...

    /**
     * 이 전화번호의 문자열 표현을 반환한다.
     * 이 문자열은 "XXX-YYY-ZZZZ" 형태의 12글자로 구성된다.
     * XXX는 지역 코드, YYY는 프리픽스, ZZZZ는 가입자 번호다.
     * 각각의 대문자는 10진수 숫자 하나를 나타낸다.
     *
     * 전화번호의 각 부분의 값이 너무 작아서 자릿수를 채울 수 없다면,
     * 앞에서부터 0으로 채워나간다. 예컨대 가입자 번호가 123이라면
     * 전화번호의 마지막 네 문자는 "0123"이 된다.
     */
    @Override public String toString() {
        return String.format("%03d-%03d-%04d", areaCode, prefix, lineNum);
    }

    public static void main(String[] args) {
        PhoneNumber jenny = new PhoneNumber(707, 867, 5309);
        System.out.println("제니의 번호: " + jenny);		//제니의 번호: 707-867-5309
    }
}

문서화를 권장하는 경우

• 전화번호나 행렬 같은 값 클래스라면 문서화를 권합니다.

특징 

• 포맷을 명시하면 그 객체는 명시적이고, 명확하고, 사람이 읽을 수 있게 됩니다.
  따라서 그 값 그대로 입출력에 사용하거나 CSV 파일처럼 사람이 읽을 수 있는 데이터 객체로 저장할 수도 있습니다.
• 포맷을 명시하기로 했다면, 명시한 포맷에 맞는 문자열과 객체를 상호 전환할 수 있는 정적 팩터리나 생성자를 함께 제공해주면 좋습니다.
  자바 플랫폼의 많은 값 클래스가 따르는 방식이기도 합니다.
  BigInteger, BigDecimal과 대부분의 기본 타입 클래스가 여기에 해당됩니다. 

 

참고 명시한 포맷에 맞는 문자열과 객체를 상호 전환할 수 있는 정적 팩터리와 생성자

ex) BIgInteger - 생성자 제공 
Java의 BigInteger 클래스는 기본적으로 toString() 메서드를 호출하면 10진수 형태의 문자열로 표현됩니다.
하지만 때로는 특정한 포맷으로 문자열을 변환하고, 그 반대로 문자열을 BigInteger 객체로 변환해야 할 수 있습니다.

BigInteger 클래스는 문자열과 BigInteger 객체 간의 변환을 지원하기 위해 생성자를 제공합니다. 
생성자는 주어진 문자열과 지정한 진법을 이용하여 BigInteger 객체를 생성합니다.

import java.math.BigInteger;

public class BigIntegerExample {
    public static void main(String[] args) {
        // BigInteger 객체 생성
        BigInteger bigInt = new BigInteger("123456789012345678901234567890");

        // BigInteger 객체를 16진수 문자열로 변환
        String hexString = bigInt.toString(16);
        System.out.println("16진수 문자열: " + hexString);	// 16진수 문자열: 18ee90ff6c373e0ee4e3f0ad2

        // 16진수 문자열을 BigInteger 객체로 변환
        BigInteger fromHexString = new BigInteger(hexString, 16);
        System.out.println("원래의 BigInteger 객체: " + fromHexString);	// 원래의 BigInteger 객체: 123456789012345678901234567890
    }
}​

ex) LocalDateTime - 정적 팩토리 메서드 제공 

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class DateTimeExample {
    private static final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

    private LocalDateTime dateTime;

    // 생성자를 통해 LocalDateTime 객체를 생성하고 저장합니다.
    public DateTimeExample(LocalDateTime dateTime) {
        this.dateTime = dateTime;
    }

    // 정적 팩터리 메서드를 통해 문자열을 받아 LocalDateTime 객체를 생성하고 저장합니다.
    public static DateTimeExample fromString(String dateTimeStr) {
        LocalDateTime parsedDateTime = LocalDateTime.parse(dateTimeStr, formatter);
        return new DateTimeExample(parsedDateTime);
    }

    // toString() 메서드를 통해 지정한 포맷으로 LocalDateTime 객체를 문자열로 변환합니다.
    @Override
    public String toString() {
        return dateTime.format(formatter);
    }

    public static void main(String[] args) {
        LocalDateTime currentDateTime = LocalDateTime.now();
        
        // DateTimeExample 객체를 생성하고 출력합니다.
        DateTimeExample example = new DateTimeExample(currentDateTime);
        System.out.println("DateTimeExample 객체: " + example);		//DateTimeExample 객체: 2023-08-01 14:26:39

        // 문자열을 DateTimeExample 객체로 변환합니다.
        String dateTimeStr = "2023-07-30 12:34:56";
        DateTimeExample parsedExample = DateTimeExample.fromString(dateTimeStr);
        System.out.println("파싱된 DateTimeExample 객체: " + parsedExample);		//파싱된 DateTimeExample 객체: 2023-07-30 12:34:56 
    }
}​

 

 

문서화의 단점: 포맷을 한번 명시하면 (그 클래스가 여기저기 많이 쓰이는 경우) 평생 그 포맷에 얽매이게 된다. 

프로그래머들이 그 포맷에 맞춰 파싱하고, 새로운 객체를 만들고, 영속 데이터로 저장하는 코드를 작성할 것입니다. 

만약, 향후 릴리스에서 포맷을 바꾼다면 이를 사용하던 기본 코드들과 데이터들은 엉망이 될 것입니다.

반대로 포맷을 명시하지 않는다면 향후 릴리스에서 정보를 더 넣거나 포맷을 개선할 수 있는 유연성을 얻게 됩니다.

 

포맷을 명시하든 아니든, 여러분의 의도는 명확히 밝혀야 합니다.

포맷을 명시하려면 아주 정확하게 해야 합니다.

 

Potion 클래스 예제: toString 반환값 포맷의 명확한 문서화 X 

public final class Potion {
    ...

    /**
     * 이 약물에 관한 대략적인 설명을 반환한다. 
     * 다음은 이 설명의 일반적인 형태이나, 
     * 상세 형식은 정해지지 않았으며 향후 변경될 수 있다. 
     * 
     * "[약물 #9: 유형=사랑, 냄새=테레빈유, 겉모습=먹물]"
     */
    @Override public String toString() {
    	...
    }
}

이러한 설명을 읽고도 이 포맷에 맞춰 코딩하거나 특정 값을 빼내어 영구 저장한 프로그래머는 나중에 포맷이 바뀌어 피해를 입어도 자신을 탓할 수 밖에 없을 것입니다.

 

참고) PhoneNumber 클래스 전체 코드: toString 추가

public final class PhoneNumber {
    private final short areaCode, prefix, lineNum;

    public PhoneNumber(int areaCode, int prefix, int lineNum) {
        this.areaCode = rangeCheck(areaCode, 999, "지역코드");
        this.prefix   = rangeCheck(prefix,   999, "프리픽스");
        this.lineNum  = rangeCheck(lineNum, 9999, "가입자 번호");
    }

    private static short rangeCheck(int val, int max, String arg) {
        if (val < 0 || val > max)
            throw new IllegalArgumentException(arg + ": " + val);
        return (short) val;
    }

    @Override public boolean equals(Object o) {
        if (o == this)
            return true;
        if (!(o instanceof effectivejava.chapter3.item11.PhoneNumber))
            return false;
        PhoneNumber pn = (PhoneNumber)o;
        return pn.lineNum == lineNum && pn.prefix == prefix
                && pn.areaCode == areaCode;
    }

    @Override public int hashCode() {
        int result = Short.hashCode(areaCode);
        result = 31 * result + Short.hashCode(prefix);
        result = 31 * result + Short.hashCode(lineNum);
        return result;
    }

    /**
     * 이 전화번호의 문자열 표현을 반환한다.
     * 이 문자열은 "XXX-YYY-ZZZZ" 형태의 12글자로 구성된다.
     * XXX는 지역 코드, YYY는 프리픽스, ZZZZ는 가입자 번호다.
     * 각각의 대문자는 10진수 숫자 하나를 나타낸다.
     *
     * 전화번호의 각 부분의 값이 너무 작아서 자릿수를 채울 수 없다면,
     * 앞에서부터 0으로 채워나간다. 예컨대 가입자 번호가 123이라면
     * 전화번호의 마지막 네 문자는 "0123"이 된다.
     */
    @Override public String toString() {
        return String.format("%03d-%03d-%04d", areaCode, prefix, lineNum);
    }

    public static void main(String[] args) {
        PhoneNumber jenny = new PhoneNumber(707, 867, 5309);
        System.out.println("제니의 번호: " + jenny);			//제니의 번호: 707-867-5309
    }
}

 

 

포맷 명시 여부와 상관없이 toString이 반환값에 포함된 필드를 제공하는 API를 제공하자 (getter)

• 예를 들어, PhoneNumber 클래스는 지역 코드, 프리픽스, 가입자 번호용 접근자를 제공해야 합니다.
• 그렇지 않으면 이 정보가 필요한 프로그래머는 toString의 반환값을 파싱할 수 밖에 없습니다.
• 성능이 나빠지고 필요하지도 않은 작업인데다, 향후 포맷을 바꾸면 시스템이 망가지는 결과를 초래할 수 있습니다.
• 접근자를 제공하지 않으면 toString 메서드를 변경될 수 있다고 문서화했더라도 그 포맷이 사실상 준-표준 API나 다름없게 됩니다. 

 

 

구글의 AutoValue 프레임워크

• 구글의 AutoValue프레임워크는 toString도 생성해줍니다. (대부분의 IDE도 마찬가지입니다)   
• 하지만, AutoValue는 클래스의 '의미'까지는 파악하지 못합니다.
• 예를 들어 앞서의 PhoneNumber 클래스용 toString과 같이 전화번호는 표준 출력 체계를 따라하는 경우에는 자동 생성이 적합하지 않고, Potion 클래스에는 적합합니다.
• 하지만 비록 자동 생성에 적합하지 않더라도 객체의 값에 관해 아무것도 알려주지 않는 Object의 toString보다는 자동 생성된 toString이 훨씬 유용합니다.

 

 

참고
대부분의 열거 타입은 자바가 이미 완벽한 toString을 제공하므로 따로 재정의하지 않아도 됩니다.
하지만 하위 클래스들이 공유해야 할 문자열 표현이 있는 추상클래스의 경우 toString을 재정의해야 합니다.
예를 들어, 대다수의 컬렉션 구현체는 추상 컬렉션 클래스들의 toString 메서드를 상속하여 사용합니다.

 

 

---

출처

https://www.yes24.com/Product/Goods/65551284

이펙티브 자바 Effective Java 3/E - 예스24