이번 장에서 다룰 내용
- 주석의 위험성 이해하기
- 가치를 더하는 주석 구별하기
- 다양한 유형의 주석 처리하기
"코드가 표현할 수 없는 것만 주석으로 처리하십시오"
- 케블린 헤니
8.1 오래된 주석 제거
오래된 주석은 작성됐을 당시에는 의도된 것이지만 코드베이스와 동기화되지 않아 완전히 잘못되었거나 오해의 소지가 있는 주석도 포함되어 있기 때문에, 우리는 여러 사정을 감안해서 그 표현에 관대하고 정당화 하려는 경향이 있다.
해당 주선은 이제 관련이 없거나 정확하지 않다는 것을 의미한다. 이런 주석은 시간을 절약해주지도 않고 읽는 데 시간이 걸리므로 삭제해야 한다.
8.2 주석 처리된 코드 제거
간혹 일부 코드를 주석 처리하고 테스트할 때가 있다. 코드를 주석 처리하고 어떤 일이 일어나는지 확인하는 것은 빠르고 쉽다. 이것은 테스트하기 좋은 방법이다. 그러나 테스트 후에는 주석처리된 코드를 모두 제거해야한다.
개발자는 Git에 브랜치를 만들고 이전 코드를 삭제하고 새로운 코드 작업을 시작한다. 코드가 작동하지 않는 것으로 판명되면 개발자는 메인 브랜치를 체크아웃하고 실험을 위해 생성된 브렌치를 삭제한다.
성공적으로 동작할 떄 개발자가 메인과 병합하면 모든 것이 깨끗해진다.
8.3 불필요한 주석 제거
코드가 주석만큼 읽기 쉬울 때 해당 주석을 불필요한 주석이라고 한다. 아무런 도움이 되지 않음 공간만 차지하므로 바로제거
//에러로그
Logger.error(errorMessage, e);8.4 메서드의 이름으로 주석 대신하기
일부 주석은 기능보다는 코드를 문서화한다.
// 코드를 문서화하는 주석
if(queryString)
fullUrl += "?" + queryString;이 경우는 주석과 동일한 이름을 가진 메서드로 블록을 추출할 수 있다.
// 변경전
///요청 url을 만듦
if(queryString)
fullUrl += "?" + queryString;
// 변경 후
///요청 url을 만듦
fullUrl = buildRequestUrl(fullUrl, queryString)
/// ...
function buildRequestUrl(fullUrl:string, queryString:string){
if(queryString)
fullUrl += "?" + queryString;
retru fullUrl;
}8.4.1 계획을 위한 주석 사용
이런 유형의 주석은 작업에 대한 계획을 세우고 작업을 세분화 할때 주로 사용된다. 이것은 로드맴을 만들 때 좋은 방법이다.
//계획을 설명하는 주석
/// 데이터를 불러옴
/// 필요 사항을 검사
/// 변형
/// Else
/// 제출8.5 불변속성을 문서화한 주석 유지
로컬이 아닌 불변속성을 문서화한 주석. <- 버그가 발생할 확률이 높은곳
이를 판단하는 방법은 '이 주석으로 누군가 버그를 만드는 것을 막을 수 있는가?'
주석을 코드로 만들 수 없는지 점건해본다. 차선으로 이런 불변속성을 검증하기 위한 테스트를 만들 수 있는가를 생각해본다. 만약 이 두가지 모두 실행할 수 없다면..? 주석을 그대로 유지!
