[자바 코딩의 기술] 3장 : 슬기롭게 주석 사용하기

3.1 지나치게 많은 주석 없애기

아무런 의미없는 주석은 없앤다.

대신 코드만 보아서는 드러나지 않는 정보를 "주석"으로 표시하자.

 

3.2 주석 처리된 코드 제거

주석 처리된 코드는 일반적인 주석과 달리 명확히 설명히 없다.

이는 코드에 혼란만 가중시키는 쓰레기를 끼얹는 것과 같다.

 

어차피 주석 처리된 코드를 다시 찾을 일은 없다. 제거하자.

 

3.3 주석을 상수로 대체

2장에서 보았던 "매직넘버" 사용 시 각 넘버에 의미에 대한 주석을 달아놓는 것은 나쁘지 않은 방법이다.

 

하지만 우리는 "상수"를 사용함으로써 주석없이 코드만으로 주석을 대체할 수 있다.

 

주석을 "상수, 변수, 필드, 메서드 이름"으로 대체할 수 있다면 바로 시도하자!

3.4 주석을 유틸리티 메서드로 대체

// round to integer percent
return Math.toIntExact(Math.round(averageFuel * 100));

위의 코드를 이해하는 것은 간단하지 않다. 그렇기에 주석을 통해 의미를 설명했다.

 

 

주석을 안쓰고 코드만으로 의미를 내포시킬 순 없을까?

int roundedToPercent = Math.toIntExact(Math.round(averageFuel * 100));

우리는 변수명에 의미를 부여하고 주석을 삭제할 수 있다. 하지만 필요없는 변수가 사용된다.

 

유틸리티 메서드

    int getAverageTankFillingPercent() {
        double sum = 0;
        for (double tankFilling : tanks) {
            sum += tankFilling;
        }
        double averageFuel = sum / tanks.size();
        return roundToIntegerPercent(averageFuel);
    }

    static int roundToIntegerPercent(double value) {
        return Math.toIntExact(Math.round(value * 100));
    }

위 코드처럼 유틸리티 메서드를 사용하면 몇가지 장점을 얻을 수 있다.

1. 코드명으로 동작에 대한 설명이 되므로 주석 삭제 가능
2. 다른 메서드 에서 만든 메서드를 재사용할 수 있다.
3. 메서드에 계층 구조가 생김으로써 상위 계층 메서드에 대한 이해도가 개선됨

결론적으로 "유틸리티 메서드"를 사용하면 주석만 제거되는 것이 아니라 코드가 더 모듈화되고 추상화 수준도 균형을 이루게 된다.

 

3.5 구현 결정 설명하기

메서드 구현 시 사용한 "자료구조"와 "알고리즘"을 왜 선택했는지에 대해 자세하게 설명하기

 

구현 결정 설명 템플릿

메서드의 [사용사례, 우려사항, 해법, 트레이드오프, 비용]까지 모두 설명한다.

/*
In the context	사용사례
facing	우려사항
we decided	해법
to achieve	품질
accepting	단점
*/

이러한 템플릿을 사용하면 코드를 이해하기 쉬워지고 미리 정의돈 구조를 따르므로 동료 개발자가 주석을 이해하기 쉽다.

 

모든 코드에 이처럼 사용하는 것은 비효율적이다.

그러므로 중요한 결정이나 까다로운 코드를 설명할 때 위 템플릿을 사용하자.

 

3.6 예제로 설명하기

class Supply {

    /**
     * The code universally identifies a supply.
     *
     * It follows a strict format, beginning with an S (for supply), followed
     * by a five digit inventory number. Next comes a backslash that
     * separates the country code from the preceding inventory number. This
     * country code must be exactly two capital letters standing for one of
     * the participating nations (US, EU, RU, CN). After that follows a dot
     * and the actual name of the supply in lowercase letters.
     */
    static final Pattern CODE =
            Pattern.compile("^S\\d{5}\\\\(US|EU|RU|CN)\\.[a-z]+$");
}

위 코드에선 사용하는 정규식의 동작에 대해 자세하게 설명했지만 어딘가 아쉽다. (이해하기 어렵다)

 

class Supply {

    /**
     * 아래 표현식은 어디서든 재고 코드를 식별한다.
     *
     * Format: "S<inventory-number>\<COUNTRY-CODE>.<name>"
     *
     * Valid examples: "S12345\US.pasta", "S08342\CN.wrench",
     * "S88888\EU.laptop", "S12233\RU.brush"
     *
     * Invalid examples:
     * "R12345\RU.fuel"      (Resource, not supply)
     * "S1234\US.light"      (Need five digits)
     * "S01234\AI.coconut"   (Wrong country code. Use US, EU, RU, or CN)
     * " S88888\EU.laptop "  (Trailing whitespaces)
    */
    static final Pattern SUPPLY_CODE =
            Pattern.compile("^S\\d{5}\\\\(US|EU|RU|CN)\\.[a-z]+$");
}

위 치럼 동작에 대해선 한 줄로 간단히 표현하고 유효한 예제와 유효하지 않은 예제를 주석을 설명하면 코드를 이해하기 훨씬 쉬워진다.

 

3.7 패키지를 JavaDoc으로 구조화하기

JavaDoc이란 자바 API가 제공하는 문서화 기능이다.

 

요약문, 전체클래스 목록 등 필요없는 표기 제외하기

 

JavaDoc이 포함해야 하는 내용

1. 소개문 : 패키지 내 클래스로 무엇을 할 수 있는지 요약 설명
2. 패키지 내 주요 클래스로 무엇을 할 수 있는지 설명하고 @link를 통해 클래스로 이동 가능하게 만듬
3. 주요 사용 사례를 어떻게 구현하는 지 보여 줄 것

3.8 클래스와 인터페이스를 JavaDoc으로 구조화

JavaDoc 작성 방법

1. 요약문과 본문을 분리해서 요약문이 잘 보이게 한다.
2. 인터페이스가 보장하는 불변과 수직으로 분리하라

3.9 메서드를 JavaDoc으로 구조화하기

    /**
     * Loads supplies onto the cargo ship.
     *
     * <p>
     * Only lets you load as many supplies as there is remaining capacity.
     *
     * Example:
     * <pre>
     * int capacity = cargoShip.getRemainingCapacity(); // 1
     * Queue&lt;Supply> supplies = Arrays.asList(new Supply("Apple"));
     * Queue&lt;Supply> spareSupplies = cargoShip.load(supplies);
     * spareSupplies.isEmpty(); // true;
     * cargoShip.getRemainingCapacity() == 0; // true
     * </pre>
     *
     * @param supplies to be loaded; must not be null
     * @return supplies that could not be loaded because of too little
     *          capacity; is empty if everything has been loaded
     * @throws NullPointerException if supplies is null
     * @see CargoShip#getRemainingCapacity() check capacity
     * @see CargoShip#unload() unload the supplies
     */
    Queue<Supply> load(Queue<Supply> supplies);

    int getRemainingCapacity();

해당 메서드의 입력과 내부 상태가 특정 출력과 상태 변경을 어떻게 보장하는 지 명시한다.

 

"설명"과 "코드 예시"가 적절히 들어갔으며 @Param, @throws 예외처리까지 명시한다.

 

@see를 통해 다른 메서드도 참조할 수 있다.

3.10 생성자를 JavaDoc으로 구조화하기

생성자는 의미있고 알맞은 이름을 생성자명에 할당할 수 없다.

 

그래서 JavaDoc 주석은 생성자에 대해 의미 정보를 적절히 설명해야 한다.

class Inventory {

    List<Supply> supplies;

    /**
     * Creates an empty inventory.
     *
     * @see Inventory#Inventory(Collection) instantiate with initial supplies //초기 제품을 초기화 하는 함수 
     */ 
    Inventory() {
        this(new ArrayList<>());
    }

    /**
     * Creates an inventory with an initial shipment of supplies.
     *
     * @param initialSupplies Initial supplies. 
     *                        Must not be null, can be empty. //생성자 종료후에 객체 상태 정보를 알려줌 (사후 정보) , 빈 상태가 되거나 초기제품으로 채워짐
     * @throws NullPointerException if initialSupplies is null  //null 입력시에 NullPointerException 반환 
     * @see Inventory#Inventory() instantiate with no supplies //제품없이 초기화 하는 함수 //두 생성자의 관계를 설명한다. 
     */
    Inventory(Collection<Supply> initialSupplies) {
        this.supplies = new ArrayList<>(initialSupplies);
    }
}

@Param는 매개변수를 설명한다.

@throws -> 발생할 수 있는 예외에 대해 설명한다.

@see -> 지금 사용하는 것 이외의 다른 대안을 제안한다.