💡 주석

• 주석은 코드 이해하는 데 도움 주는 도구
• 다만, 대충 작성하면 버그 원인이 되는 잠재적 악마

11.1 내용이 낡은 주석

• 주석과 구현 시점이 멀어지면 → 주석이 거짓말 할 가능성 높아짐
• 구현 변경 시 주석도 함께 변경해야 함

주석 ≠ 실제 코드

• 최대한 의도가 제대로 전달될 수 있도록 해야 함
• 클래스, 메소드 이름 신경써서 짓고, 주석 달기

로직 동작 설명 주석 지양

• 로직 설명하는 주석은 코드 이해에 별다른 도움 안 됨
• 오히려 실제 내용과 다른 가짜 정보 섞일 가능성 높음
• 주석 때문에 클래스, 메소드 이름 대충 짓게 됨

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

• 엉망으로 지은 클래스, 메소드 이름에 주석을 달면 안 됨
  • 로직 설명하는 작명법을 쓴 경우 주석에 의지하게 됨
  • 기능 추가나 사양변경에 주석을 신경쓰기 어려워짐 → 낡은 주석
• 주석으로 설명 추가하기보다, 메소드 이름 자체를 수정하는 것이 좋음
  • 메소드 가독성을 높이면 주석은 노 필요

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

• 코드 읽히는 목적
  • 유지 보수
  • 사양 변경
• 코드 목적 달성에 도움이 되는 주석을 작성해야 한다.
  • 유지 보수 → 로직이 어떤 의도를 갖고 움직이는가?
  • 사양 변경 → 안전하게 변경하려면 무엇을 주의해야 하는가?

Class Memeber {
		private final States states;

		// 고통받는 상태일 때 true 리턴
		boolean isPainful() {
				// 사양 변경으로 표정 변화 일으키는 상태 추가하는 경우, 이 메소드에 로직 추가
				if (states.contains(StateType.posion) ||
						states.contains(StateType.paralyzed) ||
						states.contains(StateType.fear)) {
						return true;
				}
				return false;
		}
}

11.4 주석 규칙 정리

규칙	이유
로직 변경 시 주석도 함께 변경	실제 로직과 달라져, 혼란 증가
로직 내용 설명 주석 지양	가독성 효과 없고, 주석 유지보수 어려워짐
가독성 나쁜 로직에 주석 지양, 로직 자체 가독성 증진	주석 유지보수 어려워짐, 낡은 주석 가능성
로직 의도, 사양변경 주의점 주석 달기	유지보수, 사양변경 이점

11.5 문서 주석

• 문서주석
  • 특정 형식 맞춰 주석 작성 시
    • API 문서 생성
    • 코드 에디터에서 주석 내용 팝업 표시
  • Java - Javadoc
    • /** */ 주석
  • C# - Documentation Comments
  • Ruby - YARD