[Clean Code] 4장. 주석

4장 주석

 

주석은 오래될수록 코드에서 멀어진다.

오래될수록 완전히 그릇될 가능성도 커진다.

프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니깐...!

 

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.

진실은 한곳에만 존재한다.

바로 코드다!

 

주석을 가능한 줄이도록 꾸준히 노력해야 한다.

 

---

 

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

 

코드로 의도를 표현하라!

---

 

좋은 주석과 나쁜 주석

좋은 주석

1. 법적인 주석

2. 정보를 제공하는 주석

3. 의도를 설명하는 주석

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

5. 결과를 경고하는 주석

6. TODO 주석

 : 앞으로 할 일을 TODO 주석으로 남겨두면 편하다.

 : 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애라고 권한다.

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

8. 공개 API에서 Javadocs

 

나쁜 주석

1. 주절거리는 주석

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

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

4. 의무적으로 다는 주석

5. 이력을 기록하는 주석

6. 있으나 마나 한 주석

7. 무서운 잡음

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

9. 위치를 표시하는 주석

10. 닫는 괄호에 다는 주석

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

12. 주석으로 처리한 코드

13. HTML 주석

14. 전역 정보

15. 너무 많은 정보

16. 모호한 관계

17. 함수 헤더