클린 코드 독서일지 - Day 8

좋은 주석

• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

나쁜 주석

대다수 주석이 나쁜 주석이다.

• 주절거리는 주석 : 특별한 이유 없이 의무감으로 마지못해 주석을 다는 경우. 다른 사람들에게 그 의미가 잘 전해지지 않는 주석. 이해가 안 되어 다른 모듈을 뒤져야 하는 주석.
• 같은 이야기를 중복하는 주석 : 코드 내용을 그대로 중복하는 주석. 코드보다 주석을 읽는 시간이 오래 걸릴 수 있다. 주석은 코드보다 더 많은 정보를 제공해야 한다.
• 오해할 여지가 있는 주석 : 중의적이거나, 모호하거나…
• 의무적으로 다는 주석 : 필요가 없는데도 모든 변수에 주석이 달려 있거나 한 경우. 코드를 복잡하게 만들고, 코드 업데이트를 주석이 따라가지 못해 잘못된 정보를 제공할 수 있다.
• 이력을 기록하는 주석 : 소스 코드 관리 시스템에게 맡기자.
• 있으나 마나 한 주석 : 개발자가 주석을 무시하는 습관에 빠지게 될 수 있다. 주석에 분풀이하지도 말자.
• 무서운 잡음