[Zero-base] 9-15. 주석

가독성 높이는 습관 - 주석

 

 

주석을 왜 남길까?

• 코드 덩치가 너무 큼
• 비지니스 로직이 복잡함
• 함수가 하는 일을 설명
• 파라미터와 리턴값이 의미하는 바를 설명
• 주석을 달아야하는 팀 내의 그라운드 룰 존재

 

 주석을 남기는 이유는 역설적으로 현재 코드의 품질이 낮음을 뜻함

 

 

주석의 특징

• 주석은 현실 세게에서 결코 유지보수되지 않는다.
• 하지만 현실 세계에서 정책은 늘 변한다.

 

 

무엇을 남겨야 하는가?

• 변하지 않는 것

 

• 당시 정책 결정 사유

public PaymanetResult order(User user, long orderId) {

    Order order = findOrder(user, orderId);
    /**
     * 주문과 관련된 복잡한 로직이 있다고 가정
     **/
    return payment(order);
}

private PaymentResult payment(Order order) {
    return isPeperoDay(LocalDateTime.now()) && order.hasPepero() ?
            asyncPaymentsService.payment(order) : paymentsService.payment(order);
}

private PaymentResult payment(Order order) {
    // 빼빼로데이에 빼빼로 주문 건에 한해서, 결제를 비동기로 처리함
    // 정책 결정 티켓 : https://jira.zerobase.com/zero-1000
    return isPeperoDay(LocalDateTime.now()) && order.hasPepero() ?
            asyncPaymentsService.payment(order) : paymentsService.payment(order);
}

 

• 이상한 로직이 존재해야 하는 이유

public int multiply(User user, int diceNumber, int amount) {
    // 내부 값으로 계산이 가능하지만, 정산 혹은 법적 이슈로 다른 시스템에 확인해야함
    // 관련 논의 내용 : https://jira.zerobase.com/zero-1001
    int calculatedAmount = otherSystemAdaptor.multiple(user, diceNumber);
    
    if (calculatedAmout != diceNumber * amount) {
        log.error("계산된 결과가 다름");
    }
    return calculatedAmount;
}

 

• 하위 호환성이 문제될 경우

@GetMapping("/api/foo")
public FooResponse foo(@RequestHeader("user-agent") String userAgent) {

    checkClientVersion(new ClientVersionInfo(userAgent));
    // ... 비지니스 로직 생략
    return new FooResponse();
}

private void checkClientVersion(ClientVersionInfo clientVersionInfo) {
    // 해당 버전이하에서는 A피처가 없었으므로 해당 기능 호출할 수 없음
    // or
    // 2021.01.01 하위버전 강업으로 정책이 결정됨
    // 정책 결정 티켓 : https://jira.zerobase.com/zero-1002
    if (clientVersionInfo.lessThan("1.0.0"))
        throw new RuntimeException("최신 버전으로 업데이트가 필요합니다.");
}

 

• 서비스 장애 등 사유로 기존과 다른 흐름 또는 룩 등이 추가된 경우

public void foo(Parameter parameter) {

    // ... 뭔가 복잡한 로직이 있다고 가정
    insertA(parameter.getA()); // 각각 트랜잭션 수행
    insertB(parameter.getB()); // 각각 트랜잭션 수행
    
    // DB deadlook 이슈로 업데이트를 분리함
    // 정책 결정 티켓 : https://jira.zerobase.com/error-1000
    updateB(parameter.getB());
}

 

 

정리

• 변하지 않는 것
• 당시 정책 결정 사유
• 컨텍스트를 벗어난 로직이 존재해야 하는 사유
• 하위 호환성이 문제될 경우
• 서비스 장애 등 사유로 기존과 다른 흐름/룩 등이 추가된 경우

 

 

---