Clean Code 04장. 주석

TIL(Today I Learn)

2024.06.26

오늘 읽은 범위

4장. 주석

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

1. 주석을 추가하는 이유는 코드만으로 기능을 제대로 표현할 수 없기 때문이다.
   그러므로 주석을 추가하기 앞서 코드를 다시 재검토해야 한다.

2. 주석을 피해야 하는 또 다른 이유는 주석이 항상 거짓말을 하기 때문이다.
   코드와 함께 관련 주석까지 유지보수 하는 것은 불가능에 가깝다.

3. 부정확한 주석은 차라리 없는 것이 낫다. 코드를 읽는 사람들을 속이기 때문이다.
   또한, 기능적으로 충족될 수 없는 기대를 갖게 만들며, 더이상 따를 필요가 없는 규칙에 종속되게 만든다.

4. 코드 자체에 문제가 있다는 사실을 우리 스스로 알고 있다. 자신의 잘못을 감추기 위해 주석을 추가한다.
   차라리 코드를 다시 작성하는 것이 오히려 좋다.

5. 주석을 괜찮게 사용한 케이스
   
   • 회사 코딩 표준으로 인해 법적인 이유로 작성된 주석
   • 구현에 대한 단순한 정보를 넘어서 결정 뒤에 숨은 의도를 제공하는 주석
   • 모호한 인수나 반환 값의 의미를 포함한 주석
   • 특정 결과에 대해 다른 프로그래머에게 경고성 주석
   • Javadocs in Public APIs
6. 주석을 잘못 사용한 케이스
   
   • 잘못된 코드에 대한 변명, 불충분한 결정에 대한 스스로의 정당화로 작성된 주석
   • 절차상 의무적으로 작성된 주석
   • 매우 중복되면서도 미묘하게 오해를 불러일으키는 주석
   • 모든 함수에 javadoc이 있어야 하거나 모든 변수에 주석이 있어야 한다는 규칙으로 작성된 주석
   • 모듈을 수정할 때마다 모듈 시작 부분에 의무적으로 작성된 주석
   • 소스 파일의 특정 위치를 강조하고 싶어서 작성된 주석
   • 더이상 사용하지 않는 코드를 남겨두는 용도로 작성된 주석
   • 기능과 관련 없이 쓸모 없는 정보로 작성된 주석

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

• 그동안 클린 코드가 아닌 주석을 이용하여 작성한 코드에 부가 설명을 추가한 경험이 있다.
  앞으로 리팩토링이나 클린 코드 원칙을 반영하여 개발자의 의도를 잘 표현하는 코드를 작성할 필요가 있겠다.

• 시스템 운영 경험을 하면서 분명 히스토리적으로 도움이 되는 주석들도 있었다.
  주석을 남발하는 것은 물론 좋지 않지만, 동료들에게 도움될 수 있는 주석을 선별하여 작성하는 능력은 필요하다.
  물론 코드로 모든 것을 표현하는 것이 베스트이다.

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

• 클린 코드를 작성하지 못하는 개발자가 이 책을 읽고서 주석까지 작성하지 않는다면…?
  그 개발자의 코드를 해석하고 이해하는 것이 더 어려워지지 않을까라는 걱정을 하게 되었다.
  물론 나 자신도 이런 부분에 대해서 걱정이 많다.

나의 최애 북틸

• lactofreee님의 TIL
  • 좋은 주석과 나쁜 주석을 카테고리로 잘 분류하였다.
• 카프리썬_님의 TIL
  • 이분도 좋은 주석과 나쁜 주석을 카테고리로 잘 분류하였다.
• 잇트루님의 TIL
  • 책에 나와 있는 예제 코드까지 직접 포함하여 정리하였다.