210309_B책_예제로 설명하기

오늘은 3.6<예제로 설명하기>를 진행한다.
이번 챕터는 간단하다.
예제를 주석으로 넣어 상대방이 코드를 이해하기에 편리하게 만드는 것이다.

바로 예제 코드를 보겠다.

class Supply {
/**
 * 아래 코드는 어디서든 재고를 식별한다.
 *
 * s로 시작해 숫자 다섯자리 재고 번호가 나오고
 * 뒤이어 앞의 재고 번호와 구분하기 위한 역 슬래시가 나오고
 * ...
 * 이어서 마침표와 실제 재고명이 소문자로 나온다.
 */

static final Pattern CODE = Pattern.compile("^S\\d{5}\\\\(US...)\\/[a-z]+$");
}

위 코드에는 장황한 정규식이 있다.
CODE라는 이름으로는 어디에 쓰이는지 전혀 알 수 없지만 주석이 길게 딸려 있다.
언뜻 보면 좋은 방법 같다. 최소한 코드와 더불어 주석이 있으니..
그치만 숙련된 개발자만이 바로 이해할 수 있을 것이고, 초급 개발자는 주석이 아무런 도움이 되지 못한다.
예제가 있다면 어떨까?

class Supply {
/**
 * 아래 표현식은 어디서든 재고 코드를 식별한다.
 *
 * 형식: "S<inventory-number>\<COUNTRY-CODE>.<name>"
 * 유효한 예: "S12345\US.pasta", "S08342\CN.wrench",
 * ...
 * 유효하지 않은 예:
 * "R12345\RU.fuel" (재고가 아닌 자원)
 * ....
 */

static final Pattern SUPPLY_CODE = Pattern.compile("^S\\d{5}\\\\(US...)\\/[a-z]+$");
}

주석을 생략했지만 전보다 더 길고 더 구조적이고 자세한 정보를 제공한다.
허황된 뜬구름보다 이런 정확한 예시가 더 좋은 주석이다.
또한 유효한 예와 유효하지 않은 예, 두가지를 제시함으로써 이해가 빨라졌다.
유효한 예제는 일반적으로 이러한 복잡한 표현식을 한 번에 이해할 수 있게 해준다.

테스트일 경우에는 조그만 단위 테스트를 주석으로 활용해도 좋다.
마지막으로 더 의미있는 변수명도 추가해줬다.

오늘의 코멘트: 이러한 경우에는 코드 줄이 많아져도 확실한 정보와 이해를 제공하기에 괜찮다고 생각한다.