오늘 TIL 3줄 요약

• 나쁜 코드에 주석을 달지 마라.

• 그럼에도 불구하고 주석을 달때는 좋은 주석을 달아야 한다.

• 나쁜 주석의 여러가지 예제들

TIL (Today I Learned) 날짜

2022. 04. 29

오늘 읽은 범위

4장. 주석

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

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

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

• 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다. (p.69)

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

• 코드로 의도를 표현하라! (p.70)

  • 많은 경우 주석으로 달려는 설명을 함수로 만들어 포현해도 충분하다. (p.70)

• 좋은 주석

  • 법적인 주석 (p.70)

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

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

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

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

  • TODO 주석 (p.74)

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

  • 공개 API에서 Javadocs (p.75)

• 나쁜 주석 (대다수의 주석)

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

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

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

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

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

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

    • 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라. (p.83)

  • 무서운 잡음 (p.83)

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

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

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

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

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

  • HTML 주석 (p.87)

  • 전역 정보 (p.88)

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

  • 모호한 관계 (p.89)

  • 함수 헤더 (p.89)

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

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

• 주석을 다는 것보다 코드의 가독성을 높이는데 에너지를 쏟자.

• 과거에 관례처럼 달던 주석이 소스 코드 버전 관리 시스템으로 인해 불필요해지는 경우가 많았다. 오래된 오픈소스 소프트웨어 코드에서 그러한 주석을 봤던 기억이 난다.

• 닫는 괄호에 다는 주석은 자주 보았고, 나도 가끔 블록의 크기와 깊이가 커지면 다는 것 같다. 그럴땐 해당 코드를 새로 짜야한다는 신호로 받아들여야 겠다.

• 주석을 달기보다는 가독성 좋은 클래스, 함수, 변수를 만드는 것을 의도적인 훈련을 해야 겠다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

• null

오늘 읽은 다른사람의 TIL

• null