오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨린다.
주석은 나쁜 코드를 보완하지 못한다.
표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
코드로 의도를 표현하라
코드로 의도를 설명하기 어려운 경우는 있지만 충분히 표현할 수 있다.
ex)
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((emplotee.flags & HOURLY_FLAG) &&
(employee.age > 65)
if (employee.isEligibleForFullBenefits())좋은 주석
어떤 주석은 필요하거나 유익하다. 하지만 최고의 주석은 주석을 달지 않을 방법을 찾아낸 주석이다.
- 법적인 주석: 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 수유권 정보 등등
- 의미를 명료하게 밝히는 주석: 모호한 인수나 반환값은 그 의미를 좋게 표현하면 이해하기 쉬워진다.
- TODO 주석: 요즘은 IDE를 통해 남은 TODO를 쉽게 볼 수 있으므로 편리하게 이용할 수 있다.
- 중요성을 강조하는 주석: 중요성을 강조하기 위해 주석을 사용
나쁜 주석
- 주절거리는 주석: 특별한 이유없이 달리는 주석은 필요가 없다.
- 같은 이야기를 중복하는 주석: 코드내용과 주석이 중복되면 코드를 읽는 시간보다 주석을 읽는 시간이 더 오래걸릴 수 있다.
- 오해할 여지가 있는 주석: 살짝 잘못된 정보로 인해 다른 프로그래머들에게 피해를 끼칠 수 있다.
- 의무적으로 다는 주석: 모든 변수에 주석을 달아야 한다는 규칙은 어리석은 것이다. 이런 주석들은 코드를 복잡하게 만들고, 무질서를 초래한다.
- 있으나 마나 한 주석: 기본적인 것들은 작성하지 말자.
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라:
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (module.getDependSubsystems().contains(subSysMod.getSubSystem()))위에 코드를 아래로 표현할 수 있다.
ArrayList moduleDependencies = smodule.getDependSubSystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))
- 주석으로 처리한 코드: 소스 코드 관리 시스템으로 사용해 주석코드가 필요없어졌다.
- 전역 정보: 주석을 달아야 한다면 근처에 있는 코드만 기술한다. 시스템의 코드가 변하면 다른 곳에 있던 코드의 주석이 변한다는 보장이 없기 때문이다.
- 모호한 관계: 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다. 즉 자세히 작성해야 한다.
느낀점: 주석은 필수라고 생각했다. 내가 쓴 코드는 잘 알아보지만 남이 봤을 때는 알아보지 못하는 코드를 작성한적이 많았다. 그래서 주석을 작성하여 설명을 많이하였는데 이 4장 파트를 읽으면서 주석을 작성하는 것보다 코드를 더 명확하게 구현한느 것이 더 중요하다는 것을 느꼈다.