3. 주석

주석을 다는 목적은 코드를 작성하는 사람이 알고 있는 정보를 코드를 읽는 사람에게 전달하는 것 이다.

코드에서 명확하게 드러나지 않는 내용이 무엇인지 파악하고 주석으로 처리하는 것

■ 설명하지 말아야 할 것

    - 코드 자체에서 재빨리 도출될 수 있는 사실

    - 나쁜 함수명과 같이 나쁘게 작성된 코드를 보정하려고 애쓰는 주석 그렇게 할 시간에 코드를 수정해라

■ 코드에 기록 해야하는 것

    - 코드가 특정한 방식으로 작성된 이유를 설명해주는 내용 ( 감독의 설명 )

    - 코드에 담긴 결함, TODO 혹은 xxxx같은 표시를 사용하라

    - 특정 상수가 특정 값을 가지게 된 사연

    - 코드를 읽는 사람이 자기가 작성한 코드의 어느 부분을 보고 뭐라고? 라는 생각을 할지 예측해보고, 그부분에 주석을 달 것

    - 평범한 사람이 예상하지 못할 특이한 동작을 기록 할 것

    - 파일이나 클래스 수준 주석에서 큰 그림을 설명하고 각 조각이 어떻게 맞춰지는지 설명하라

    - 코드에 블록별로 주석을 달아 세부 코드를 읽다가 나무만 보고 숲은 못 보는 실수를 저지르지 마라

    - 사람들이 쉽게 빠질 것 같은 함정을 경고하라

주로 사용 되는 표시

- TODO  아직 하지 않은 일 | 해야할 일

- FIXME  오동작을 일으킨다고 알려진 코드

- HACK  아름답지 못한 해결책

- XXX    위험!, 여기 뭔가 문제가 있다

- TextMate  ESC

코드의 이러저러한 내용을 훗날 수정할 거라는 생각이 들면, 그러한 생각을 주석으로 작성하는 일은 당연하게 받아들여야 한다는 사실

주석은 코드를 읽는 사람에게 코드의 질이나 상태 그리고 추후 개선 방법 등을 제시하여 소중한 통찰을 제공한다

■ 주석에 많은 정보를 담는 방법

    - it, this　같은 대명사가 여러가지를 가리킬 수 있따면 사용하지 않는 것 이 좋다

    - 함수의 동작을 실제로 할 수 있는 한도 내에서 최대한 명확하게 설명하라

    - 신중하게 선택된 입/출력 예로 주석을 서술하라

    - 코드가 가진 의도를 너무 자세한 내용이 아니라 높은 수준에서 개괄적으로 설명하라

    - 같은 줄에 있는 주석으로 의미가 불분명한 함수의 인수를 설명하라

    - 만은 의미를 함축하는 단어로 주석을 간단하게 만들어라