javadoc

javadoc

    규칙 70 - 스레드 안전성에 대해문서로 남겨라.

    클래스를 사용할 때 클래스의 객체와 정적 메서드가 병렬적으로 이용되었을 때, 어떠한 부작용이 있을 수 있는지 안전한지에 대한 정보가 없으면 추후에 큰 문제를 야기할 수있다. JavaDoc에서 synchronized 키워드를 통해 병렬설 지원 여부를 확인할 수있다고 알고 있으나 실상 그렇지 않다. 왜냐하면 Javadoc이 만드는 문서에는 Javadoc이 들어가지 않는다. 왜냐하면 synchronized 키워드는 메서드의 구현 상세에 해당하는 정보이며, 공개 API의 일부가 아니기 때문이다. 그렇기 때문에 synchronized 키워드를 통해 판단해서는 안되고 병렬적으로 사용해도 되는지의 여부는 문서에 남겨져 있어야 한다. 출처 : 조슈아 블로크, 『 Effective Java 2/E』, 이병준 옮김, 인사..

    규칙 62 - 메서드에서 던져지는 모든 예외에 대해 문서를 남겨라.

    메서드를 올바르게 사용하려면 메서드에서 던져지는 예외에 대한 설명이 문서에 있어야 한다. 그리고 메서드가 던질수있는 모든 무점검 예외까지 선언할 필요는 없지만 점검지점 예외들과 마찬가지로주의해서 문서로 남겨놓으면 좋다. 특히 Javadoc @throws 태그를 사용해서 메서드에서 발생 가능한 모든 무점검 예외에 대한 문서를 남겨야 한다. 하지만 메서드 선언부의 throws 뒤에 무점검 예외를 나열하지는 말아야 한다. 요약하자면 메서드가 던질 가능성이 있는 모든 예외를 문서로 남겨라. 점검지점 예외, 무점검 예외도 남겨라. 이를 지키지 않으면 해당 API를 사용하는 다른사람들이 효과적으로 사용하는게 어려워진다. 출처 : 조슈아 블로크, 『 Effective Java 2/E』, 이병준 옮김, 인사이트(201..

    메서드- 규칙 38 인자의 유효성을 검사하라.

    만약 메서드에서 파라미터 값으로 전달되는 값을 제한해야 하는 경우 어떤 값이 들어오면 시스템이 죽거나, 잘못된 데이터가 나온다는 것을 기재해 놓아야 한다. 그렇지 않으면 심각한 문제가 발생될 수 있다. 그렇기 때문에 몇 가지 안전장치를 마련해야 한다. 방법 - 만약 인자 유효성을 위반하는 경우는 Javadoc의 @throw 태그를 사용하여 문서화 해야 한다. 1234567/** * * @throw ZeroDivisionException (0으로 나누었을 때)*/public int getData() { return 222/0;}Colored by Color Scriptercs - assertion을 이용하여 인자 유효성 체크할 수 있다. - assertion은 항상 참이 되어야 한다. 만족되지 못하면 As..