사실 이미 지나버렸는데, ("금요일 오전 6시까지"를 "금요일 까지"라고 생각해 버렸다...) 그래도 읽은게 있으니 아쉬워서 4장도 정리한다.

일할땐 Windows를 쓰는데, 집에서는 Mac을 쓰려니 키보드가 도무지 익숙해지지 않는다.

abstract

나쁜 코드에 주석을 달지 마라. 새로 짜라.
-- 브라이언 W. 커니핸 P.J. 플라우거

보통 프로그래밍 언어의 주석은 말그대로 주석, 즉 코드의 일부분에 대한 설명이다. 그런데 사실 많은 이들은 프로그래밍 언어를 또다른 외국어로 비유하는데, 컴퓨터와 소통하기 위해 사용하는 언어라는 의미로 이야기한다. 근데 우리는 소통을 하기 위해 그 언어의 의미를 다시 해석해서 써야하는가?

프로그래밍 언어에 익숙해지면 간결한 코드와 self explanitory 이름들이 코드의 뜻을 적당히 잘 전달하기 때문에 주석 자체를 최대한 줄여야 한다는게 이 장의 핵심이다.

4장 주석

진실은 한곳에만 존재한다. 바로 코드다.

코드는 프로그램의 진화와 유지보수에 함께하지만 보통 주석은 그렇지 못한다. 그러니 주석을 추가하지 말고 코드를 정리하고, 표현을 강화하자.

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 대문이다.

보통 코드에 주석을 다는 상황은 자신의 코드가 지저분하기 때문이다.

• 지저분한 코드를 고치는 행위가 주석을 추가하는 것보다 좋다.
• 코드로 의도를 표현하라. 조건문의 조건이 너무 복잡해서 주석이 필요하면 조건의 뜻이 내포된 함수(메서드)를 만들어라.

좋은 주석

• 정보를 제공하는 주석
  • 정규표현식은 한눈에 어떤 패턴을 찾기 위한 용도인지 알아보기 힘든 경우가 많다.
  • 이런 경우 그 개념을 주석으로 달아두면 좋다.
• 의도를 설명하는 주석
  • 왜 이렇게 구현하였는지에 대한 주석
  • 특히 남의 코드 보다보면 궁금한 경우들이 좀 있는 듯...
• 의미를 명료하게 밝히는 주석
  • 표준 라이브러리 등에 정의되어 직접 함수 이름 등으로 의미를 표현하기 힘든 경우
  • 주석의 일반적인 오류
• 결과를 경고하는 주석
  • 경우에 따라 프로그램에 위험한 결과를 불러일으킬 수 있는 경우
  • Thread Safety와 같은 이슈에 대하여
• 중요성을 강조하는 주석
  • 지워도 될것같은 코드의 존재 목적을 설명하는 경우
• 법적인 주석
  • 저작권, 소유권 정보, 저자 등
  • 모든 내용 명시보단 표준 라이선스, 외부 라이브러리 참조 등을 넣어주는 것도 괜찮다.
• TODO
  • 나(aquashdw)는 게을러서 노트를 남겨두지 않으니까
  • 다른분들은 이슈 트래커로 이쁘게 정리도 해두자
• Javadocs
  • 공개 API를 만든다면 Javadocs를 추가하면 좋다.
  • 그 외 다른 언어들도 비슷한거 있겠지?

순서는 책과 조금 다르게 작성해보았다. 겉이 있을 때 읽히기 좀더 쉬울것 같은 느낌으로...

나쁜 주석

나머지는 다 나쁜 주석이지만 책에는 어느정도 분류를 나누어서 설명해준다. 근데......음 솔직히 열거식으로 작성되서 몇가지를 제외하면 소제목만 나열해도 요약이 된다.

• 주절거리는 주석

  미묘한 말인데...약간 혼잣말 같은 주석?을 의미하는것 같다.

  try {
      // ... 중략 (이건 내가 코드를 생략했다는 뜻!)
  } catch (IOException e) {
      // 속성 파일이 없다면 기본값을 모두 메모리에서 읽어 들였다는 의미다.
  }

  책에 나와있는 예시, try 블럭은 생략했다. (이 주석도 나쁜 주석인가) catch 블럭의 주석은 정확한 의미

  • 이전에 읽었는지,
  • 읽었다면 누가 읽었는지,
  • 아니면 나중에 읽는 부분을 만들것이란 뜻인지

  등의 의미중 하나일 수 있다.

• 같은 이야기를 반복하는 주석

  코드가 이미 주석의 내용을 표현하고 있다면 그냥 코드를 읽으면 된다.

  책에는 추가로 Tomcat의 예시가 나와있는데, Apache 관련 스택들에서 흔히 보던 주석이다. 변수 이름은 좋게 쓰여있는데, 거기에 추가로 Javadoc 주석이 덧붙어 있다.

• 오해의 여지가 있는 주석

• 의무적으로 다는 주석

• 이력을 기록하는 주석 & 공로를 돌리거나 저자를 표시하는 주석

  • 주석보다 Git이 헐씬 쎄다.

• 있으나 마나 한 주석

• 함수나 변수로 표현할 수 있다면 주석을 달지 마라.

• 위치를 표시하는 주석
  가끔 코드 중간에 길게 주석으로 ASCII 아트마냥 레이블을 다는 경우가 있는데, 남용하면 좋지 못하다.

• 닫는 괄호 주석
  중첩이 지나치게 심할 경우 괜찮지만, 애초에 중첩이 심하면 코드를 정리하는게 더 좋을지도

• 주석으로 처리한 코드

• HTML 주석
  주석에 HTML을 포함하는 경우. Markup은 사용하는 도구가 진행함이 바람직하다.

• 전역 정보

• 너무 많은 정보

• 모호한 관계

• 함수 헤더

• 비공개 코드에서 Javadoc
  어차피 외부에서 사용하지 않는다면 내용을 설명하는 Javadoc이 필요 없다.

음...(결론)

이번장은 읽을때는 몰랐는데 정리하려고 보니까 지금 우리는 모르는 내용이 좀 많은것 같다. 아무래도 개발자라는 직종이 내 나이보다 오래된 직종이기도 하고, 옛날엔 지금의 도구들이 없었을테니 정착한 주석들도 있지 않을까 싶다. 물론 그래도 Java 진영에 있는 한 Kafka도 있고 Tomcat도 있고 이런 주석은 여러 곳에서 만날 수 있다. 그래도 공부하면 주석의 내용도 이해되고, 개발도 할 수 있다. 이는 문제가 되지 않는다고 본다.

아마 작가님이 이야기하는 것은 "세상은 변해가고 있으니 옛날의 주석을 고집할 필요가 없다" 아니었을까? Java는 우리나라에서 가장 널리 퍼져있으며 그만큼 역사도 오래된 언어이다. 그리고 아마 같은 개발자 선배들이 위의 "나쁜 주석"에 해당하는, 옛날에는 "좋은 주석"들을 다는게 습관이 되어계실 가능성이 높다.

나도 처음에는 이런 부수적 정보 제공 목적의 주석을 "멋지게" 작성하는 선임들의 모습이 인상깊었고, 열심히 따라하려고 했던 적이 있었다. 그런데 그만두엇다. 단체로 개발하는 팀의 일원이 아니게 된건 둘째 치더라도, 일단 귀찮은것 + 코드를 읽는게 더 쉽다는 체감 때문에. 아마 나도 엉클 밥이 말한 잘못된, 유지보수되지 못한 주석을 읽은게 아니었을까 싶다.

앞에 나왔던 내용중에 "주석은 유지보수되지 않는다. 코드는 요구사항에 따라 변화한다."라고 이야기했다. 코드가 변화한다는건 결국 묵은 습관을 청산하고 주석을 다는 방식, 나아가 코드를 작성하는 방식도 변화해야 한다는 의미 아닐까?

음....마지막 내용이 좀 두서없긴 하지만 어쨋든 코드를 열심히 쓰자. 주석은 논문에 달자.