반응형
『Clean Code(클린 코드) 애자일 소프트웨어 장인 정신 - 로버트 C. 마틴』 을 읽고 요약한 내용입니다.
나쁜 코드에 주석을 달지 마라. 새로 짜라
브라이언 W. 커니핸, P.J. 플라우거
우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 그러므로 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
- 주석은 나쁜 코드를 보완하지 못한다.
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
- 코드로 의도를 표현하라
- 확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다. if ((emplotee.flags & HOURLY_FLAG) && (employee.age > 65) // 다음 코드와 비교하면? if (employee.isEligibleForFullBenefits())
좋은 주석
- 법적인 주석
- 구현 표준에 맞춰 법적인 이유 등으로 특정 주석 명시
- 정보를 제공하는 주석
// yyyy/MM/dd UTC 형식이다- 의도를 설명하는 주석
- 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명
- 의미를 명료하게 밝히는 주석
- 때때로 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용
- 결과를 경고하는 주석
// 여유시간이 충분하지 않다면 실행하지 마십시오
// SimpleDateFormat 은 스레드에 안전하지 못하다. 따라서 각 인스턴스를 독립적으로 생성해야 한다.- TODO 주석
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
- 공개 API를 구현한다면 반드시 훌륭한 Javadocs 작성을 추천한다. 하지만 여느 주석과 마찬가지로 Javadocs 역시 독자를 오도하거나, 잘못 위치하거나, 그릇된 정보를 전달할 가능성이 존재하는 것 역시 잊으면 안 된다.
나쁜 주석
대다수의 주석이 이 범주에 속한다. 일반적으로 대다수 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등 프로그래머가 주절거리는 독백에서 크게 벗어나지 못한다.
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
- 있으나 마나 한 주석
- 무서운 잡음
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
- 위치를 표시하는 주석
- 닫는 괄호에 다는 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드
- HTML 주석
- 전역 정보
- 너무 많은 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드에서 Javadocs
그동안 코드를 작성하면서 달았던 주석들이 떠오르며 그 주석들을 옆에서 지적받은 느낌이 들었다. 특히나 오해할 여지가 있는 주석을 꽤 달지 않았나 하는 생각이 들었다. 다른 개발자가 내 주석을 다르게 해석할 수 있지 않았나 생각하게 됐다.
또한, 변수로 정의함으로써 주석을 줄이면서 코드로 표현하고 개선할 수 있는 점을 생각하게 됐다. 변수명을 명확히 작성하지 않고, 주석으로 버무리면 된다면 안일했던 것이 생각났다. 주석을 남발하는 것보다 애초에 이름을 명확하게 정의하여 코드를 개선하는 방식을 적절한 때에 사용하도록 해야겠다.
반응형