[내 코드가 그렇게 이상한가요?] 11장 주석:유지 보수와 변경의 정확성을 높이는 주석 작성 방법

 

1. 내용이 낡은 주석

 

처음 개발 내용과 달리 이후에 사양이 변경되면서 주석까지 유지 보수하지 못한 경우입니다. 주석이 낡아 버리지 않게, 구현을 변경할 때 주석도 함께 변경하는 것이 좋습니다.

 

 

1) 주석은 실제 코드가 아님을 이해하기

 

 

2) 로직의 동작을 설명하는 주석은 낡기 쉽다

코드의 동작을 그대로 설명하는 주석은 코드를 변경할 때마다 주석도 변경해야 할 것입니다. 만약 실수로 변경하지 않으면, 로직과 주석 사이에 괴리가 생깁니다.

 

 

 

 

2. 주석 때문에 이름을 대충 짓는 예

메서드는 주석으로 설명을 추가하기보다, 메서드의 이름 자체를 수정하는 것이 좋습니다.

 

메서드의 가독성을 높이면, 주석으로 설명을 추가하지 않아도 됩니다. 그러면 내용이 낡은 주석이 생길 가능성도 줄어듭니다.

 

 

 

 

 

3. 의도와 사양 변경 시 주의 사항을 읽는 이에게 전달하기

 

코드는 언제 어떠한 목적으로 읽힐까요? 기본적으로 유지 보수할 때와 사양을 변경할 때 읽힙니다. 

 

 

코드 유지 보수 시 읽는 사람이 주의를 기울여야 하는 부분은 '이 로직은 어떤 의도를 갖고 움직이는가'입니다. 

 

 

그리고 사양을 변경할 때 읽는 사람이 주의를 기울여야 하는 부분은 '안전하게 변경하려면 무엇을 주의해야 하는가'입니다.

 

class Member{
    private final States states;
    
    // 고통받는 상태일 때 true를 리턴
    boolean isPainful(){
    	// 이후 사양 변경으로 표정 변화를
        // 일으키는 상태를 추가할 경우
        // 이 메서드에 로직을 추가합니다.
        if(states.contains(StateType.poison) ||
           states.contains(StateType.paralyzed) ||
           states.contains(StateType.fear)){
        	return true;
        }
        
        return false;
    }
}

 

 

 

 

 

 

4. 주석 규칙 정리

 

규칙	이유
로직을 변경할 때는 반드시 주석도 함께 변경해야 함.	주석을 제대로 변경하지 않으면, 실제 로직과 달라져 주석을 읽는 사람에게 혼란을 줌.
로직의 내용을 단순하게 설명하기만 하는 주석은 달지 않음.	실질적으로 가독성을 높이지 않고, 주석 유지 보수가 힘듦. 결과적으로 내용이 낡은 주석이 될 가능성이 높음.
가독성이 나쁜 로직에 설명을 추가하는 주석은 달지 않음. 대신 로직의 가독성을 높여야함.	주석 유지 보수가 힘들고, 갱신되지 않아 낡은 주석이 될 가능성이 높음.
로직의 의도와 사양을 변경할 때 주의할 점을 주석으로 달아야 함.	유지 보수와 사양 변경에 도움이 됨.

 

 

 

 

 

5. 문서 주석

문서 주석이란 특정 형식에 맞춰 주석을 작성하면, API 문서를 생성해 주석나 코드 에디터에서 주석의 내용을 팝업으로 표시해 주는 기능입니다. 

 

예시 - Java의 Javadoc, C#의 Documentation comments, 루비의 YARD