💻 주석은 나쁜 코드를 보완하지 못한다. 코드로 의도를 표현하라
"자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!" (p.69)
💻 좋은 주석
- 법적인 주석
ex) 저작권 정보, 소유권 정보 등 법적 정보 - 정보를 제공하는 주석
ex) 정규 표현식의 의미, 리턴값의 의미 - 함수 구현 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
ex) 인수, 리턴값의 이름을 바꿀 수 없는 경우 그 의미 - 결과를 경고하는 주석
ex) 실행할 때 주의해야 하는 테스트케이스 - TODO 주석
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
💻 나쁜 주석
"있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라. 더 낫고, 행복한 프로그래머가 되는 지름길이다." (p.83)
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
- 있으나 마나 한 주석
- 무서운 잡음
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
- 위치를 표시하는 주석
- 닫는 괄호에 다는 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드
- HTML 주석
- 전역 정보
- 너무 많은 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드에서 Javadocs
📝 느낀점
이번 장을 읽는 내내 든 생각은 내가 아마 벌써 이 책에 세뇌당했을 지도 모르겠다는 생각이었다. 특히 좋은 주석의 예를 들어 주는 부분을 읽으면서는 '그래도 주석으로 쓰는 것보다는 함수 자체에 표현을 잘 하면 되지 않느냐'는 생각이 계속 들었다. 지난 2, 3장을 읽을 때 저자가 제시하는 코드의 지향점에 크게 공감을 했기 때문인 것 같다. 또, 나쁜 주석의 예를 읽을 때는 짜증이 나서 제대로 읽지도 않았다.. 주석이 코드 이해에 하나도 도움이 되지 않는 그런 주석들이 덕지덕지 달라 붙어 있는 코드는 그 누구도 읽기 싫을 것 같다.
여태 나름대로 알아 듣기 힘든 복잡한 부분은 주석을 달아서 설명을 하고는 했는데, 그것보다는 함수를 깨끗하고 정확하게 쓰는 것이 더 좋은 습관이라는 것을 다시 한 번 깨닫는다. 다행히 IDE와 Git이 많이 발전했기 때문에 보다 쉽게 깨끗한 코드를 쓸 수 있게 되었다. 주석을 구구절절 달지 않아도 코드만으로 하고 싶은 이야기를 다 할 수 있는 개발자가 될 수 있도록 노력해야 겠다.
