클린 코드 독서일지 - Day 9

나쁜 주석

• 함수나 변수로 표현할 수 있는 주석 : 주석을 통해 코드를 이해시키기보다, 주석이 필요하지 않도록 코드를 개선하는 편이 좋다.
• 위치를 표시하는 주석 : 배너 역할을 하는 주석. 배너를 남용하면 흔한 잡음으로 여겨지므로, 반드시 필요할 때만 드물게 사용하라.
• 닫는 괄호에 다는 주석 : 닫는 괄호 뒤에 어떤 블록이었는지 표시하는 주석. } // while, } // try 같은 것들. 중첩이 심하고 장황한 함수라면 도움이 될지도 모르지만 작게 잘 나누어진 함수들에선 잡음이다. 그러므로 닫는 괄호에 주석을 달기보다 함수를 쪼개고 줄여 보자.
• 공로를 돌리거나 저자를 표시하는 주석 : 소스 코드 관리 시스템에 저장하자.
• 주석으로 처리한 코드 : 좋지 않은 관행이다. 주석으로 처리한 코드는 다른 사람들이 지우기를 주저하게 되고, 결국 쓰지 않는 코드임에도 쓰레기처럼 남는다. if의 코드를 기억하는 일은 소스 코드 관리 시스템에 맡기자. 주석으로 처리할 필요는 없다.
• HTML 주석 : 읽기 어렵다.
• 전역 정보 : 주석 근처에 있는 코드가 아닌, 시스템 어딘가에 있는 다른 코드를 설명하는 주석. 이 경우 해당 코드가 변해버리면 주석이 함께 업데이트되기 어렵다. 주석을 달아야 한다면 근처에 있는 코드만 기술하자.
• 너무 많은 정보 : 독자에게 불필요한 정보는 적지 말자.
• 모호한 관계 : 주석과 코드 간의 관계가 명백하지 않으면 안 된다.
• 함수 헤더 : 짧은 함수는 긴 함수 헤더가 필요 없다.
• 비공개 코드에서 Javadocs : 공개하지 않을 코드라면 산만한 Javadocs 형식을 갖출 필요가 없다.