주석은 나쁜 코드를 보완하지 못한다.
"코드에 주석을 추가하는 주된 이유는 코드 품질이 나쁘기 때문이다. 따라서, 주석을 달지 말고 코드로서 그것을 명확히 설명할 수 있도록 코드를 수정하는 것이 바람직하다."
코드로 의도를 표현하라!
"주석을 통해 코드를 설명하기 보다, 코드를 통해 설명할 수 있는 방법을 찾아라. 대대수 의도는 코드로 표현 가능하다."
좋은 주석
"어떤 주석은 필요하고 유익하다. 하지만, 정말로 좋은 주석은 주석을 달지 않은 방법을 찾아낸 주석이다."
의도를 설명하는 주석
때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명하게 된다. 이러한 주석은 코드를 읽는 사람으로 하여금 더 나은 이해를 돕는다.
의미를 명료하게 밝히는 주석
간혹 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 더 이해하기 쉬워진다. 물론 인수나 반환값 자체를 명확히 만든다면 더 좋지만, 표준 라이브러리나 변경할 수 없는 코드의 경우 주석이 유용하다.
하지만 이 경우에도 올바르지 않은 주석을 달게 될 위험성은 존재한다. 따라서, 주석을 달게 될 때는 더 나은 방법을 항상 고민하는 것이 좋다.
결과를 경고하는 주석
코드를 읽고 사용하는 사람에게 작성한 코드의 실행 결과에 대한 경고는 좋은 주석이다. 오히려 이 경우 주석을 달지 않았을 때의 위험성이 더 클 수 있다.
중요성을 강조하는 주석
코드에서 별 것 아니라고 생각하고 넘어갈 수도 있는 부분에 주석을 달게 됨으로써 그 중요성을 강조한다.
나쁜 주석
"대부분 주석이 여기에 속한다."
같은 이야기를 반복하는 주석
코드의 내용으로 충분히 설명할 수 있는 내용을 주석으로 다시 표현하는 것은 중복이다. 오히려 주석으로 하여금 잘못된 이해를 불러 일으킬 수 있다.
함수나 변수로 표현할 수 있다면 주석을 달지 마라
주석을 달지 않고 코드를 변경하고, 코드로써 명확히 의도를 표현할 수 있다면 주석을 달지 않는 것이 좋다.
닫는 괄호에 다는 주석
중첩이 심하고 장황한 함수라면 닫는 괄호에 주석을 다는 것이 의미가 있을 지도 모른다. 하지만 이러한 상황이라면 함수 자체를 줄이려고 시도하는 것이 더더욱 의미가 있다.
주석으로 처리한 코드
코드가 주석 처리 되어 있는 것 만큼 의미 없는 주석도 없다. 읽는 사람으로 하여금 큰 오해를 불러 일으킨다.
전역 정보
주석을 달아야 한다면 근처에 있는 코드만 기술해라. 주석을 달았으나 근처에 있는 코드에 대한 주석이 아니라면 읽는 사람은 또 다시 코드를 뒤져봐야 한다.
