코드 작성 시에 주석은 무척 중요하다.
다른 사람 기준은 어떤지 모르겠지만 내가 상각하는 코드 주석은 크게 봐서 2가지로 나눌 수 있다.
- 메소드, 클래스, 파일 등 코드의 집합에 대한 설명
- 코드 집합 내부에서 코드 중간에 나타나는 주석
메소드, 클래스 등의 주석은 예를 들어 JavaDoc 형태로 이 메소드와 클래스를 사용하는 다른 개발자들의 이해를 돕기 위해 당연히 적어야 한다.
논란이 되는건 두 번째 주석이다.
개인적으로는 그냥 참고할 만한 책 정도인 클린 코드에서도 주석에 대해 언급한 구절이 있다. 여기서 좋은 주석의 여러 특징을 설명하는데, 이 특징을 관통하는 중요한 키워드는 바로 why 즉 왜 이 코드를 이렇게 작성했는가이다.
예를 들어 정책적으로 해외 업무 파트너 매칭이 2개로 한정되어 있다면 분명 어딘가 상수로 정의해놨을거다. 이 경우 이런 주석이 유용하다.
/** 블라블라에 의거하여 최대 해외 업무 파트너 수는 2개입니다. */
const MAX_OVERSEA_PARTNERS = 2;
다만 코드에 대해서 설명하는 부분을 주석으로 다는건 최대한이 지양해야 한다. 이 경우는 남들이 보기에 코드를 이해하기 어렵게 짰거나, 스스로가 코드에 대해서 못미더운 경우라 생각한다.
좀 어렵거나 복잡한 로직일 경우 종종 마주하게 되는데, 이런 경우에는 자주 쓰는 방법이 있다. 일단 해당 로직을 주석으로 세세하게 적어본다. (1) 이를 코드로 변환하고 (2) 코드로 변환이 끝난 주석을 삭제한다. 1, 2를 계속 반복했는데도 남아있으면 그 주석은 살아남을 가치가 있으니 남겨둔다.
다만 주의해야 할 점은, 변수명이다. 클린 코드는 영어가 네이티브인 미국분께서 지으신 책이라 함수나 변수명으로 커버할 수 있는 주석은 척결 대상이라고 하지만 불행히도 우리는 한국인이라서 이 부분은 적당히 합의를 할 수 있어야 한다.
그래도 다 영어로 적어야 하는게 아니냐고?
자 그럼 여러분, 아래 단어를 변수명으로 만드시오(배점 10점)
- 일반 과세시 과표
- 미징수 보수/세금액
- 중도인출가능금액
- 세제혜택시 과표
WHY 주석은 좋은가
결론은 아니다. WHY 주석은 비즈니스 요구사항, 개발 제약 사항 등을 명시해놓은 주석인데, 이 역시 문서의 한 종류이기 때문에 **“유지보수하지 않는 모든 문서는 시간이 지나면 효용성이 급격히 감소한다”**라는 문서의 원죄를 피해갈 수는 없다.
사업이 잘 된다는 조건 하에 시간이 지나면 비즈니스 요구사항이 변경할 가능성이 95%이지 않을까.
그렇기 때문에 뭐… 음… 이건 정답이 없다 🥲