TIL (Today I Learned)

2022.02.24

오늘 읽은 범위

4장. 주석

책에서 기억하고 싶은 내용을 써보세요.

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

• 주석은 실패한 코드다. (p. 68) - 사실상 주석은 기껏해야 필요악이다.

  • 실패를 만회하기 위해 주석을 사용한다. 주석은 언제나 실패를 의미한다. 때로는 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 그래서 주석은 반겨 맞을 손님이 아니다.

  • 주석이 필요한 상황에 처하면 곰곰이 생각해서, 상황을 역전해 코드로 의도를 표현하고, 의도를 표현할 때마다 스스로 칭찬해준다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

• 코드는 변화하고 진화한다. 불행히도 주석은 언제나 코드를 따라가지 못한다.

• 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. (p. 69)

• 진실은 한 곳에만 존재한다. 바로 코드다. (p. 69)

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

• 좋은 주석 (p. 70)

  💡 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실!

  • 법적인 주석 (p. 70)

  • 정보를 제공하는 주석 (p. 71)

  • 의도를 설명하는 주석 (p. 71)

  • 의미를 명료하게 밝히는 주석 (p. 72)

  • 결과를 경고하는 주석 (p. 73)

  • TODO 주석 (p. 74)

  • 중요성을 강조하는 주석 (p. 75)

• 나쁜 주석 (p. 75) - 대부분의 주석

  • 주절거리는 주석 (p. 76)

  • 같은 이야기를 중복하는 주석 (p. 77)

  • 오해할 여지가 있는 주석 (p. 79)

  • 의무적으로 다는 주석 (p. 80)

  • 이력을 기록하는 주석 (p. 80)

  • 있으나 마나 한 주석 (p. 81)

    • 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라. 더 낫고, 행복한 프로그래머가 되는 지름길이다. (p. 83)

  • 무서운 잡음(Docs 주석에 불필요하게 달린 주석들) (p. 83)

  • 위치를 표시하는 주석 (p. 84)

  • 닫는 괄호에 다는 주석 (p. 85)

  • 공로를 돌리거나 저자를 표시하는 주석 (p. 86)

  • 주석으로 처리한 코드 (p. 86)

  • HTML 주석 (p. 87)

  • 전역 정보 (p. 88)

  • 너무 많은 정보 (p. 88)

  • 모호한 관계 (p. 89)

  • 함수 헤더 (p. 89)

  • 비공개 코드에서의 javadocs (p. 90)

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

이번 장에서는 주석의 불필요성에 대해 이야기한다.

모든 주석이 불필요 하다는 말은 아니지만 최대한 코드를 깔끔하게 정리하고 표현력을 강화해서 애초에 주석이 필요 없는 방향으로 가라고 이야기 한다.

요즘에 주석을 다는 이유는 딱 하나다. 해야 할 일은 많은데 기획 되어 있지 않은 일들이 계속 밀려 들어 와서이다. 일 하다 보면 새로운 급한 작업으로 인해 기존 작업이 밀리게 되고, 밀린 작업은 완성되지 않았기에 주석이 없으면 짜던 내용을 잊어 버리기 일쑤다. Todo 주석을 이용해 하던 부분까지 정리를 해 놓지 않는 이상 다시 작업할 때 곤란한 경우가 태반이기 때문이다. 나이가 들어감에 따라 기억력이 감퇴되어 어쩔 수 없는 현상이라 타협하곤 한다.

글을 읽고 과감하게 어제 주석으로 처리해 뒀던 코드를 삭제해 버렸다. 다시 필요하지는 않겠지...