Clean Code 읽기(4)

4장 주석

나쁜 코드에 주석을 달지 마라. 새로 짜라 이 한마디로 정리할 수 있을것 같다.

• 주석은 나쁜 코드를 보완하지 못한다.

  보통 주석을 다는 이유가 ‘더러운 코드’에 대한 변명이다. 코드 품질이 나쁜 코드에 주석을 달아봤자 보완하지 못한다. 코드를 짜는데에 시간을 보내자.

• 코드로 의도를 표현하라

  메서드나 변수 이름을 통해 의도를 충분히 표현할 수 있다.

• 좋은 주석

  • 법적인 주석
  • 정보를 제공하는 주석
  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
  • 결과를 경고하는 주석
  • TODO 주석
  • 중요성을 강조하는 주석
  • 공개 API에서 Javadocs

몇몇 주석은 확실히 코드의 보조역할을 할 수 있다는것을 알 수 있다. 물론 아직 큰 단위의 팀 프로젝트는 해보지 않았기에 법적인 주석 등은 이해만 가고 공감은 가지않았다.

• 나쁜 주석
  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
  • 있으나 마나 한 주석
  • 무서운 잡음
  • 함수나 변수로 표현할 수 있다면 주석을 달지마라
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하는 주석
  • 주석으로 처리한 코드
  • HTML 주석
  • 전역 정보
  • 너무 많은 정보
  • 모호한 관계
  • 함수 헤더
  • 비공개 코드에서 Javadocs
  • 예제

변수, 함수를 작성할 때 이름이 갖는 중요함을 알 수 있었다. 같이 보고있는 리팩토링 책에서도 이름을 강조했었는데, 이름을 잘 짓는것만으로 주석이 필요없는 코드가 될 수 있다는걸 직접 코드를 작성하면서 느낄 수 있었다.

학교 과제로 나오는 프로젝트 대부분이 주석을 작성하라고 되어있다. 그 습관들 때문에 나쁜코드 - 의무적으로 다는 주석, 있으나 마나 한 주석 등을 많이 작성했었다. 지금 생각해보면 왜 과제로 그런 요구를 주는지 이해가 가지 않는다. 채점하는데 참고하기위해서? 차라리 변수 함수명을 대충 짓거나 파악이 불가능하면 감점이라고 했으면 쓸모없는 주석을 다느라 코드가 길어지는것을 막을 수 있지 않을까..라고 생각한다.

또한 대학교에서 기본적인 프로그래밍 수업을 할 때 ‘이름 짓기’를 좀 확고하게 알려줬으면 한다는 생각이 들었다. 계속해서 컴공/컴소, 코딩을 새로배우는 학생들이 생길테고 이름의 중요성을 강조하지 않으면 ‘옛날의 나(지금도 부족하지만..)’같은 학생들이 계속 양산될텐데..라고 느꼈다.

더 확장해서 드는 생각이 나도 이제와서 태형이형이 많이 알려주셔서 배운게 많은데, 신입생이나 갓 복학한 친구들에게 멘토라는 존재가 있으면 좋겠다라는 생각이 들었고, 지금 간단하게 느낀점들이 언젠가는 누군가에게 도움을 줄 수 있으면 좋겠다라고 느꼈다.