[Book - Clean Code] 4. 주석

주석을 사용하여 코드의 주장을 명확하게 알려주는 것도 좋지만,
코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로 하여 애초에 주석이 필요 없는 코드를 작성하는 것이 더 중요하다고 생각한다.

부정확한 주석은 독자를 현혹하고 오도하며, 결코 이뤄지지 않을 기대를 심어주기 때문에 아예 없는 주석보다 훨씬 더 나쁘다.
더 이상 지킬 필요가 없는 규칙이나 지켜서는 안 되는 규칙을 명시하기도 한다.
따라서, 코드만이 정확한 정보를 제공하는 유일한 출처이다. 그러므로 간혹 필요할지라도 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

주석이 유용하다 할지라도 가능하다면 함수 이름에 정보를 담는 편이 더 좋다.

인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.

때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다. 예를 들어, 특정 테스트 케이스를 On/Off 할 때이다.
요즘에는 @Ignore 속성을 이용해 테스트 케이스를 꺼버리기 때문에 구체적인 설명은 @ignore 속성에 문자열로 넣어준다.

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용한다.

대다수 주석이 나쁜 주석에 속한다.
일반적으로 대다수 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등
프로그래머가 주절거리는 독백에서 크게 벗어나지 못한다.

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.
이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다.

있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리해라.
함수나 변수로 표현할 수 있다면 주석을 달지 마라. 즉, 주석이 필요하지 않도록 코드를 개선하는 편이 더 좋다.

닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도해라.

주석을 달아야 한다면 근처에 있는 코드만 기술해라.
코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.

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

주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.

그동안 주석을 그냥 달았던 것 같다.
앞으로는 필요한 주석만을 의미가 명확하게 쓰도록 하고, 되도록이면 주석을 달지 않아도 되는 코드를 만들어 보도록 하자.