주석은 코드를 부연 설명해주는 역할을 한다.
하지만 주석으로 좋지 않은 방법으로 짜인 코드를 보완하진 못한다.
표현력이 풍부하고 깔끔하게 짜여진 코드는 주석이 사실상 거의 필요가 없다.
간단한 예를 들어보자
//직원에게 복지 혜택을 받을 자격이 있는지 확인한다.
if((employ.flags & HOURLY_FLAG) && (employee.age > 65));
if(employ.isEligibleForFullBenefits());
위 두 if문은 같은 비교를 하지만 누가 봐도 주석을 달지 않고도 코드만으로 의도를 분명히 할 수 있다.
이와 같이 대다수의 경우 주석으로 만들려는 설명을 함수로 풀어 표현하기에 충분하다.
하지만 특정한 경우에는 주석이 필요할 순 있다.
좋은 주석
- 법적인 주석
- 특정 회사가 정한 구현 표준에 맞춰 법적인 이유로 특정 주석으로 넣으라고 명시하는 경우이다.
각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 반드시 따라줘야 한다. - 정보를 제공하는 주석
- 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
다음 코드에 주석은 추상 메서드가 반환할 값을 정의한다.
//테스트 중인 Responder 인스턴스를 반환
protected abstract Responder reponderInstance();
하지만 위에서 말했듯이 함수 이름을 responderBeingTested로 풀어 작성하면 굳이 주석이 필요하진 않다.
- 의도를 설명하는 주석
- 코드 구현을 이해하게 도와주는 선을 넘어 코드 작성 방향 결정에 깔린 의도를 설명할 수 있다. - 의미를 명료하게 밝히는 주석
- 일반적으로 인수나 반환값을 명료하게 표현하도록 만들면 더 좋지만, 인수나 반환 값이 표준 라이브러리 거나
변경하지 못하는 코드라면 도움을 주는 주석을 만들 수 있다.
물론 잘못된 이해로 잘못된 주석을 잘아 놓는 위험도 따를 순 있다.
이것이 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 위험한 이유가 된다.
그러므로 먼저 주석이 필요 없는 코드로 작성이 불가능할지 고민하고 여의치 않다면 정확히 달아야 한다. - 결과를 경고하는 주석
- 협업하는 프로그래들에게 결과를 경고할 목적으로 주석을 사용할 수 있다.
테스트를 위한 코드인 경우 @Ignore 속성을 사용하여 테스트 케이스를 끌 수 있다.
@Ignore("실행에 많은 시간이 걸림")
하지만 JUnit4가 나오기 전에는 메서드 이름 앞에 _기호를 붙이는 게 관례였다고 한다.
아래 코드는 주석이 적절한 예이다.
public static SimpleDateFormate makeStandardHttpDateFormat(){
//SimpleDateFormat은 스레드에 안전하지 않음.
//따라서 각 인스턴스를 독립적으로 생성해야 함.
SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
return df;
}
- TODO 주석
- 프로그래머가 앞으로 해야 할 일 또는 구현해야 할 부분을 //TODO 주석을 사용하여 남기면 알아보기 쉽다.
보통은 필요하다 판단하지만 당장 구현하기엔 어려움이 따를 때 기술한다. - 중요성을 강조하는 주석
- 대수롭지 않다고 여겨질 수 있는 무언가의 중요성을 강조할 수 있다.
//여기서 trim을 사용해 공백을 잘라줘야 한다.
//trim 미수행시 다른 문자열로 인식함.
String itemCount = match.group(5).trim();
...
- 공개 API에서 Javadocs
- 표준 자바 라이브러리에서 사용한 Javadocs는 유용하게 쓰인다.
이 처럼 공개 API를 구현한다면 반드시 Javadocs도 함께 작성해주도록 하여 보는 사람의 이해를 도울 수 있다.
하지만 Javadocs 역시 오도되거나 잘못 위치하면 위험성을 내재하게 되니 주의가 필요하다.
'클린 코드' 카테고리의 다른 글
[클린 코드] 형식 맞추기(1) (0) | 2022.01.11 |
---|---|
[클린 코드] 주석(2) (0) | 2022.01.05 |
[클린 코드] 함수(3) (0) | 2021.12.29 |
[클린 코드] 함수(2) (0) | 2021.12.27 |
[클린 코드] 함수(1) (0) | 2021.12.27 |