#3. 주석은 리팩토링의 신호다

주석도 리팩토링의 대상일까요?

리팩토링을 하여 구조를 변경하였다면 관련 주석도 변경해야 할까요?

앞서 말씀드렸듯이 주석만 읽고 코드를 분석하는 프로그래머들을 위해 반드시 필요합니다. 주석이 현재 구조와 다르다면, 주석만 읽는 분들은 오히려 잘못된 정보로 더 혼란스러워질 수 있죠. 이미 말씀드렸죠? 잘못된 주석은 잘못된 코드보다 더 !!!위험!!!합니다.

이런, 그럼 오히려 주석이 나중에 더 큰 문제가 되지는 않을까요? 코드를 리팩토링하기도 바쁜데, 리팩토링 결과에 따라 주석도 일일이 수정해야 한다니… 이거야 말로 정말 시간 낭비 아닌가요?

맞는 말입니다. 시간 낭비죠. 여러분이 생각하듯이 주석이 많으면 눈을 어지럽혀 코드를 읽기가 힘들고, 변경된 코드에 따라 주석도 일일이 바꾸기도 힘들죠. 주석만 읽고 분석하자니, 주석이 정확한 내용인지도 믿기 힘들고, 참 난감하군요.

그렇다고 주석을 적지 않는다면, 소스코드 분석에 지쳐 코드는 금새 백만라인이 되고 제품은 시장에서 매장되겠죠? 아 이런, 어쩌란 말인가요?

앞서 말씀드린 SetAngle 함수에 주석을 한번 달아 볼까요?

// 전달받은 angle 만큼 shape의 Center점을 중심으로 하여 회전시킨 후 화면을 repaint 한다.
// 오류 발생시 shape은 이전 상태의 각도값을 그대로 가진다.
// angle : shape의 각도값(상대값 아님).
//         Degree. 0~360의 범위를 가지며 그 이외의 값은 스스로 보정한다.
void Shape::SetAngle(FLOAT angle) {
    // 코드 구현
}

눈이 어지러우시죠? 도대체 코드는 어디있고 4줄이나 되는 기나긴 저 주석은 또 뭐란 말입니까?

바로 리팩토링을 하라는 !!!신호!!!입니다.

여러분, 혹은 여러분의 팀원이 차후에 리팩토링이 되어야 한다고 알려주는 것입니다. 주석이 없어지도록 멋지게 리팩토링 하세요.

제가 한번 해볼께요. 더 좋게 하실 수 있는 분은 더 좋게 만들어 보시구요.

// 오류 처리 : 강한 보증
void Shape::Rotate(const Degree& delta, const bool repaint /*= true*/) /* throw() */ {

    SetAngle(GetAngle() + delta, this->GetCenter());
    if (repaint) Draw();
}

일단 주석을 4줄에서 1줄로 줄였습니다. 문장도 짧군요. 아까보다 눈에 더 잘 들어 오시리라 생각합니다.

1. Degree라는 클래스를 만들어 전달할 인수가 Degree 형태라는 것을 명시했습니다. 아울러 클래스 이므로 0 ~ 360 범위를 넘어서면 정규화될 것이라는 믿음을 심어 주었습니다.

2. delta 라고 인자를 두어 상대값이라는 것을 명시했습니다.

3. repaint 인자를 두어 상황에 따라 화면을 갱신할 수 있다는 것을 명시했습니다.

4. shape의 각도를 저장하는 함수가 아니라, 실제로 회전시킨다는 의미로 함수명을 Rotate라로 변경했습니다.

5. 별도의 SetAngle함수를 두어 shape의 각도값 세팅 방법을 명시했습니다.

6. SetAngle 함수에 GetCenter() 값을 전달하여 shape의 Center점을 중심으로 회전시킨다는 것을 명시했습니다.

7. 예외 명세 throw()를 주석으로 적어 예외발생을 하지 않는다는 것을 명시했습니다.

8. 오류 발생시 강한 보증을 하여 오류로 인한 데이터 변경이 없다는 것을 명시했습니다.

9. 코드로 충분히 설명이 되는 주석들은 지웠습니다.

코드가 2줄밖에 안되니 분석하는데 시간이 걸리지도 않을 것이며, 주석을 통한 설명보다 더 눈에 잘 들어 옵니다.

기능구현 초기에 작성된 주석은 여러 단계의 리팩토링을 걸쳐 점차 사라져야 합니다. 막연히 이제 팀원들이 다 아는 사항이니까 그냥 지워야지… 하고 바로 지워버리면 안됩니다. 새로 입사한 팀원이 난감해 지겠죠?

또 코드가 명쾌하게 주석의 내용을 설명하고 있는데, 불필요하게 주석으로 주절주절 설명하면 안됩니다. 눈만 어지럽히죠.

코드가 명쾌하게 주석의 내용을 설명할 수 있도록 이름변경, 구조변경 등을 한 뒤 주석을 지우세요. 주석이 점차 없어지고, 코드는 간결해지고, 분석도 용이해집니다. 다음번 리팩토링시에 주석을 동기화하는 시간 낭비도 없어지죠.

사실 제가 주석으로 분석하고, 주석을 기능구현 전에 미리 작성하라고 말씀드렸지만, 궁극적으론 이처럼 소스코드가 간결하고 명쾌해서 주석없이도 손쉽게 분석이 되어야 됩니다.

다시한번 말씀드리지만 주석이 없어지도록 리팩토링 하세요.

잊지마세요.

1. 주석은 리팩토링의 !!!신호!!!입니다.

2. 주석은 리팩토링의 !!!힌트!!!입니다.

3. 주석은 리팩토링 과정을 거쳐 소스코드에서 사라져야 합니다.

4. 주석이 없어지도록 리팩토링하면 소스 가독성이 !!!증가!!!합니다.