주석을 달려고 하지 말고 코드로 의도를 표현하라.
쓸데 없는 주석은 읽는 개발자가 주석을 무시하는 습관에 빠지게 한다. 결국 코드가 바뀌면서 주석은 거짓말로 변한다.
[좋은 주석]
법적인 주석
저작권 정보와 소유권 정보
의도를 설명하는 주석
: 내가 왜 이 함수를 만들었는지에 대한 설명
(ex. //스레드를 대량 생성하는 방식으로 어떻게든 경쟁 조건을 만들려 시도한다.)변경할 수 없는 코드인데 의미가 모호할 때
인수나 반환 값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
결과를 경고
(ex. 여유 시간이 충분하지 않다면 실행하지 마십시오.)TODO 주석
- 더 이상 필요 없는 기능을 삭제하라는 알림
- 누군가에게 문제를 봐달라는 요청
- 더 좋은 이름을 떠올려 달라는 부탁
- 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의
[나쁜 주석]
오해할 여지가 있는 주석
```java
//this.closed가 true일 때
if(!closed){
...
}
``` 살짝 잘못된 정보로 인해 this.closed가 true로 변하는 순간에 함수가 반환되리라는 생각으로 어느 프로그래머가 자기 코드가 굼벵이 기어가듯 돌아가는 이유를 찾느라 골머리를 앓는다.
이력을 기록하는 주석
(→ 코드 관리 시스템 이용)
위치를 표시하는 주석
(ex. 코드 중간에 끼워 넣는 `//Actions///////////////`)닫는 괄호에 다는 주석
: 중첩이 심하고 장황한 함수일 때만,,,, while{...} //while
주석으로 처리한 코드
: 주석으로 처리된 코드는 다른 사람이 지우기를 주저한다.
html 주석
: javadocs와 같은 도굴 주석을 뽑아 웹페이지에 올린다면 html 태그가 들어간 주석은 위험
전역정보
: 주석자체가 다시 설명을 요구하면 안됨
