[클린코드][4장] - 주석

안녕하세요 Dibrary입니다.

클린코드 4장은 코드를 작성하면서 같이 기록하는 주석에 대한 내용입니다.
주석도 의도하지 않게, 읽는데 방해가 되거나 하는 요소가 될 수 있으니 깔끔하게 작성하고자 할 때 참고하시면 좋을 듯 합니다.

 

---

1. 코드로 의도를 표현하자

코드를 설명하는게 아니라 코드가 무슨 목적으로, 무슨 기능을 하기 위한건지 주석으로 남기자는 것입니다.

 

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

즉, 변수나 함수 이름으로 해당 내용 표현이 된다면 주석이 필요 없을 것입니다. 

주석을 달지 않도록 코드를 작성하는 것이 가장 기본입니다.

 

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

주석이 관련 코드를 설명하는 게 아니라 넘어오는 값의 상태나, 해당 함수 동작 이전의 전제조건을 언급한다면 적절한 위치가 아닙니다.

 

---

좋은 주석의 종류

1. 정보를 제공하는 주석
2. 의미를 명료하게 밝히는 주석
3. 결과를 경고하는 주석
4. TODO 주석
5. 중요성을 강조하는 주석

---

나쁜 주석의 종류

1. 목적 없이 작성된 주석
2. 같은 이야기를 중복하는 주석
3. 읽고 나서 오해할 여지가 있는 주석
4. 작성 의무때문에 달아 놓은 주석
5. 너무 당연한 사실을 언급해놓은 주석
6. 저자를 표시하는 주석
7. HTML 주석
8. 너무 많은분량으로 관련없는 정보를 담은 주석