1. 주석을 최대한 쓰지 말자.
1.1 주석은 나쁜 코드를 보완하지 못한다.
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
- 자신이 저지른 난장판을 주석으로 설명하지 말고 개선하는 데 시간을 보내야 한다.
- 코드로도 의도를 표현할 수 있다.
예제 1. 나쁜 예와 좋은 예
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && employee.age > 65))
// 의미 있는 이름을 지으면 해결된다.
if (employee.isEligibleForFullBenefits())1.2 주석은 방치된다.
- 코드의 변화에 따라가지 못하고, 주석은 방치된다.
- 코드는 컴파일되어 호출되지만 주석은 그저 주석이기 때문에 그 자리에 방치되고 결국 의미없는 텍스트가 되어버리는 경우가 허다하다.
2. 좋은 주석
2.1 구현에 대한 정보를 제공한다.
// kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeFormat = Pattern.compile("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*");- 이 정규식은 어떤 뜻인지 이해하기 어렵다. 이러이러한 포맷이다라는 정보를 제공해준다.
2.2 의도와 중요성을 설명한다.
// 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트를 만들도록 함.
for (int i = 0; i < 25000; i++) {
someThread someThread = ThreadBuilder.builder().build();
}
// 유저로부터 입력받을 값을 저장할 때 trim으로 공백제거 필요
String userName = userNameInput.trim();TODO, FIXME 주석
- TODO : 앞으로 할 일. 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 떄.
- FIXME : 문제가 있지만, 당장 수정할 필요는 없을 때. 가능하면 빨리 수정하는게 좋다.
- IDE에서 하이라이팅되고, 별도의 윈도우에서 볼 수 있다.
3. 주석보다 annotation
java.lang.annotation
- annotion : 코드에 대한 메타 데이터
- 코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다.
- @Deprecated : 컴파일러가 warning을 발생시킴. IDE에서 사용시 표시됨.
- @NotThreadSafe : ThreadSafe하지 않음을 나타냄. (책에서는 주석으로 표현했지만 현재는 어노테이션을 많이 사용)
- @Nullable : 값이 null이 될 수 있다는 것을 알려준다.
4. JavaDoc
- Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구
- 팀 외부의 개발자들은 내가 작성한 코드를 사용하기 어려워하기 때문에, 라이브러리를 Javadoc을 통해 기술하듯이 Javadoc을 작성하기도 한다.
- 팀 내에서도 중요한 부분들은 Javadoc으로 정리하기도 한다.
// 한줄 주석
/*
* 여러줄 주석
*/
/**
* 자바독
*/
do for me