[Effective Java] 상속을 고려해 설계하고 문서화하라

상속용 클래스는 내부 구현을 문서로 남겨야 한다.

'외부' 클래스를 사용한다는 것은 프로그래머에게 통제권이 없어 언제 어떻게 변경될지 모른다는 의미를 갖는다. 따라서 상속용 클래스를 만들 때는 메서드를 재정의하면 어떤 일이 일어나는지 정확히 정리하여 문서로 남겨야 한다. (public, protected 메서드 중 final이 아닌 모든 메서드)
    => 어떤 순서로 호출하는지, 각각의 호출 결과가 이어지는 처리에 어떤 영향을 주는지 등

Implementation Requirements

• API 문서의 메서드 설명에 있는 문구로, 메서드의 내부 동작 방식을 설명하는 곳이다.
• @implSpec태그를 붙여주면 자바독 도구가 생성해준다.

주의

1. 상속용 클래스의 생성자는 어떤 방식으로든 재정의 가능 메서드를 호출하면 안된다.

public class Super {
    public Super() {
        overrideeMe();
    }

    public void overrideeMe();
}

public final class Sub extends Super {
    private final Instant instant;

    Sub() {
        instant = Instant.now();
    }

    @Override public void overrideMe() {
        System.out.println(instant);
    }

    public static void main(String[] args) {
        Sub sub = new Sub();
        sub.overrideMe();
    }
}

여기서 instant가 두 번 출력되어야 할 것 같지만 한 번은 null이 찍힌다. 상위 클래스의 생성자는 하위 클래스의 생성자가 인스턴스 필드를 초기화하기도 전에 overrideMe를 호출하기 때문이다.