[독서 기록-Clean Code] 4장. 주석

1.주석에 대하여

주석을 다는 것은 코드로 표현하지 못했다는 뜻이므로 실패를 뜻한다. 주석이 오래될수록 코드에서 멀어진다. 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

2.주석은 나쁜 코드를 보완하지 못한다

주석으로 설명하려고 애쓰기보다 주석이 필요 없게 코드를 깨끗이 정리해라.

3.코드로 의도를 표현하라

주석을 다는 대신 함수 이름을 고쳐라.

4.좋은 주석

1) 법적인 주석

저작권 정보, 소유권 정보 등

2) 정보를 제공하는 주석

편리하기는 하지만 주석이 없는 편이 더 낫다.
ex. 추상 메서드의 반환값

3) 의도를 설명하는 주석

4) 의미를 명료하게 밝히는 주석

인수나 반환값 자체를 명료하게 만들면 더 좋겠지만, 변경 불가능한 경우 의미를 명료하게 밝히는 주석이 유용하다.

5) 결과를 경고하는 주석

다른 프로그래머의 실수를 면할 수 있기 때문에 여기서의 주석은 합리적이다.

6) TODO 주석

프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다(ex. 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려달라는 부탁, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등). 하지만 TODO로 떡칠한 코드는 바람직하지 않다. 주가적으로 없애도 괜찮은 TODO 주석은 없애라.

7) 중요성을 강조하는 주석

8) 공개 API에서 Javadocs

공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성해야 한다. 하지만 여느 주석과 마찬가지로 Javadocs 역시 독자를 오도하거나, 잘못 위치하거나, 그릇된 정보를 전달할 가능성이 존재하므로 주의한다.

5.나쁜 주석

대부분의 주석이 포함된다.

1) 주절거리는 주석

주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다. 주석의 의미를 알아내기 위해 다른 코드를 뒤져봐야 한다면 좋은 주석이 아니다.

2) 같은 이야기를 중복하는 주석

코드 내용을 그대로 중복하는 주석은 지양하자. 주석을 읽는 데 더 오랜 시간이 걸리거나 코드를 지저분하게 만들 뿐이다.

3) 오해할 여지가 있는 주석

주석에 담긴 '살짝 잘못된 정보'로 인해 코드의 원래 뜻을 놓칠 수 있다.

4) 의무적으로 다는 주석

모든 함수나 변수에 주석을 달아야 한다는 규칙은 어리석다.

5) 이력을 기록하는 주석

예전에는 모듈 첫머리에 변경 이력을 기록하고 관리하는 것이 관례였다. 하지만 소스 코드 관리 시스템이 있는 현재는 필요 없다. 완전히 제거하는 편이 좋다.

6) 있으나 마나 한 주석

너무 당연한 사실을 언급하여 개발자가 주석을 무시하는 습관에 빠지게 할 수 있다.

7) 무서운 잡음

목적이 없는 주석을 작성하지 마라.

8) 함수나 변수로 표현할 수 있다면 주석을 달지 마라

주석을 다는 대신 코드로 표현해라.

9) 위치를 표시하는 주석

일반적으로 가독성만 낮추므로 제거하라. 아니면 반드시 필요할 때만, 드물게 사용하라. 남용하면 독자가 흔한 잡음으로 여겨 무시할 수 있다.
ex.

// Actions /////////////////////////////////

10) 닫는 괄호에 다는 주석

닫는 괄호에 다는 주석은 중첩이 심하고 장황한 함수에서 도움이 될지도 모른다. 하지만 주석을 달기보다 함수를 줄이는 방향으로 노력하라.

11) 공로를 돌리거나 저자를 표시하는 주석

주석 처리 대신 소스 코드 관리 시스템에 저장하라.
ex.

/*Richard가 추가함*/

12) 주석으로 처리한 코드

주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 그러므로 점차 쓸모없는 코드가 쌓인다. 주석 처리된 코드는 삭제하고, 대신 소스 코드 관리 시스템을 사용하라.

13) HTML 주석

HTML 주석은 주석을 읽기 쉬워야 하는 편집기/IDE에서조차 읽기 어렵다.

14) 전역 정보

주석의 내용은 근처 코드와 관련이 있어야 한다. 코드와 멀리 떨어져 있다면 코드가 변해도 주석이 같이 변하리라는 보장이 없다.

15) 너무 많은 정보

주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.

16) 모호한 관계

설명을 위해 주석을 달았다면 주석 자체가 또 다른 설명이 필요하게 해서는 안 된다.

17) 함수 헤더

함수 헤더를 추가한 함수보다 짧고, 한 가지만 수행하며 이름을 잘 붙인 함수가 훨씬 더 좋다.

18) 비공개 코드에서 Javadocs

공개 API는 Javadocs가 유용하지만 공개하지 않은 코드라면 Javadocs는 쓸모가 없다. 시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요는 없다.