11장 주석: 유지 보수와 변경의 정확성을 높이는 주석 작성 방법

읽는 사람을 혼란스럽게 만드는 주석은 무엇인지 살펴보고, 읽는 사람에게 도움을 주어 유지 보수와 변경의 정확성을 높이는 주석 작성 방법에 대해 알아보자!

---

11.1 내용이 낡은 주석

class Member {
	private final States state;
	
	// 힘든 상태일 때 true 리턴
	// 중독, 마비 상태일 때 true 리턴
	boolean isPainful() {
		if (states.contains(StateType.poison) ||
			states.contains(StateType.paralyzed) ||
			states.contains(StateType.fear)) {
			return true;
		}
		return false;
	}
}

• 주석에는 중독, 마비 상태만 적혀있는데 실제 로직은 세 가지 상태를 판정하고 있다.
• 처음 사양에서 isPainful은 중독, 마비만 판정 대상이었지만 이후에 사양이 변경되면서 공포 상태가 추가되어 문제가 발생한 것이다.
• 왜 주석과 실제 코드가 일치하지 않은 사례가 많을까?
  • 코드에 비해 주석을 유지 보수하는 것이 어렵기 때문이다. 코드를 변경할 때 주석도 함께 변경하면 좋겠지만, 업무가 바쁘고 충분히 주의하지 않으면 주석까지 유지 보수하기는 힘들다.
• 주석이 낡아 버리지 않게, 구현을 변경할 때 주석도 함께 변경하는 것이 좋다. 이때 주의할 점은 다음과 같다.

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

• 클래스와 메서드의 이름이나 주석의 설명은 실제 코드가 아니므로 실제 내용을 100% 전달할 수 없다. 그래도 최대한 의도가 제대로 전달될 수 있게 클래스와 메서드의 이름을 짓고, 주석을 달아야 한다.

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

• 코드의 동작을 그대로 설명하는 주석은 코드를 변경할 때마다 주석도 변경해야 한다.
• 이러한 주석은 말 전하기 게임과 같다. 말이 전해지면서 조금씩 과장되거나 누락되어, 실제 내용과 다르게 바뀔 가능성이 있다.
• 추가로, 주석 때문에 클래스와 메서드의 이름을 대충 짓게 되는 문제도 있다.

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

// 수면, 마비, 혼란, 석화, 사망 이외의 상황에서 행동 가능
boolean isNotSleepingAndIsNotParalyzedAndIsNotConfusedAndIsNotStoneAndIsNotDead() { ... }

• 이처럼 주석을 달면 갱신하기 어려워 낡은 주석이 되기 쉽다. 또한 뭔가 추가된다면 주석도 함께 변경해야 한다.
• 이와 같은 메서드는 주석으로 설명을 추가하기 보다, 메서드의 이름 자체를 수정하는 것이 좋다.

boolean canAct() { ... }

• 메서드의 가독성을 높이면, 주석으로 설명을 추가하지 않아도 된다.

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

• 코드 유지 보수 시 읽는 사람이 주의를 기울여야할 부분은 ‘이 로직은 어떤 의도를 갖고 움직이는가’ 이다.
• 사양을 변경할 때 주의를 기울여야할 부분은 ‘안전하게 변경하려면 무엇을 주의해야 하는가’ 이다.

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

11.4 주석 규칙 정리

규칙 이유

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

11.5 문서 주석

• 특정 형식에 맞춰 주석을 작성하면, API 문서를 생성해 주거나 코드 에디터에서 주석의 내용을 팝업으로 표시해 주는 기능. 예를 들어 자바의 JavadocJavadoc 태그 용도

  @param	매개변수 설명
  @throw	throw 되는 예외 설명
  @return	리턴 값 설명