[Clean code] 4장. 주석

"나쁜 코드에 주석을 달지 마라. 새로짜라"
주석은 그 어떤 정보보다 유용하다. 하지만 주석은 필요악이다. 우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기위해 위해 주석을 사용한다.

---

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

2. 코드로 의도를 표현하라!

되도록이면 주석을 달지 않고 코드로 의도를 표현하라.

3. 좋은 주석

어떤 주석은 필요하거나 유익하다.

1) 법적인 주석: 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 명시

2) 정보를 제공하는 주석: 기본적인 정보를 반환

3) 의도를 설명하는 주석

4) 의미를 명료하게 밝히는 주석: a.compareTo(b) = -1 ; // a < b

5) 결과를 경고하는 주석 : 요즘은 Junit의 @Ignore 등의 속성으로 인해 테스트를 무시할 수 있다.

6) TODO주석 : 하지만 TODO로 떡칠한 코드는 바람직하지 않다. 그러므로 주기적으로 TODO주석을 점검해 없애도 괜찮은 주석은 없애라.

7) 중요성을 강조하는 주석: 자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용

8) 공개 API 의 javadoc

4. 나쁜 주석

대다수의 주석이 이 범주에 속한다.

1) 주절거리는 주석: 주석을 달기로 결정했다면 충분히 생각하여 최고의 주석을 달자.

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

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

4) 의무적으로 다는 주석 : 모든 함수에 javadocs를 달거나 모든 변수에 주석을 다는 경우 코드를 더 복잡하게 만들며 가독성이 떨어진다.

5) 이력을 관리하는 주석: 이제는 소스 코드 관리시스템이 널리 보급되어있으니 이력 관리 주석을 달지 않도록 하자.

6) 있으나 마나 한 주석

7) 무서운 잡음: 때로는 javadocs도 잡음이다.

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

9) 위치를 표시하는 주석: 때때로 프로그래머는 소스 파일에서 특정위치를 표시하려 주석을 사용한다. 너무 자주 사용하지 않는다면 배너는 눈에 띄며 주의를 환기하지만 일반적으로 이와 같은 주석은 가독성만 낮춘다. 그렇기 때문에 꼭 필요한 경우에만 사용하자.

10) 닫는 괄호에 다는 주석: 닫는 괄호에 주석을 달기보다 함수를 줄여쓰려고 노력하자.

11) 주석으로 처리한 코드: 주석으로 처리한 코드는 다른 개발자가 지우기도 애매하다. 의도가 있을거라 생각들기 때문이다. 지금은 소스관리 시스템으로 코드가 관리하니 주석으로 코드를 처리하지 말자.

12) HTML 주석: HTML주석은 최악이다. 도구로 주석을 뽑아 웹페이지에 올릴작정이면 프로그래머가 하지말고 도구를 사용하자.

13) 전역정보: 주석을 달아야 한다면 근처에 있는 코드만 기술하라

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

15) 함수 헤더: 짧고 잘만든 함수가 함수헤더를 다는거 보다 좋다.

---

결론은 주석을 다는 것보다 함수가 무엇을 나타내는지 명확하게 코드를 짜야 된다는 것 같다 🤔