클린코드 - 4장

🔖 4장 : 주석

읽은 날짜 : 2024.08.27

지은이 : 로버트 C. 마틴

출판사 : 인사이트

 

기억하고 싶은 내용

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

• 코드만으로 의도를 표현하는 것을 우선으로 해야 한다.
• 주석이 거의 없는 코드가 복잡한 주석이 많이 달린 코드보다 좋다.

 

좋은 주석이란?

• 법적인 주석 
  • 저작권, 소유권 정보, 표준 라이선스, 외부 문서 등
• 정보를 제공하는 주석
  • 표현력 있게 코드를 작성하면 필요 없어질 수 있다.
• ✅ 구현 의도를 설명하는 주석 
• 인수나 반환값의 의미를 명료하게 밝히는 주석
• ✅ 결과를 경고하는 주석 
  • ~하지 마세요, ~해야 합니다 등
• ✅ TODO 주석 
  • 앞으로 할 일, 필요하지만 당장 구현하기 어려운 업무 등
• ✅ 그냥 넘어갈 수 있는 부분의 중요성을 강조하는 주석 
• 공개 API의 Javadocs

 

나쁜 주석이란?

• 코드 내용을 그대로 설명하는 주석
• 오해할 여지가 있는 주석
  • 코드보다 읽기 어렵고 잘못된 정보가 포함된 경우
• 의무적으로 다는 주석
  • 모든 함수에 Javadocs를 넣을 필요는 없다.
  • 비공개 코드라면 Javadocs는 굳이 필요하지 않다.
• 변경 이력을 기록하는 주석
  • 버전 관리 시스템이 있기 때문에 완전히 제거하는 것이 좋다.
• 너무 당연해서 새로운 정보를 제공하지 못하는 주석
  • 읽는 사람이 오히려 부주의하게 넘기기 쉽다.
• 위치를 표시하는 주석
  • e.g. // Actions /////////////////////////
  • 반드시 필요한 경우에만 사용해야 한다.
  • 적절한 들여쓰기와 포맷팅, 함수와 변수에 의미를 부여하는 것으로 주석을 없앨 수 있다. [참고]
• 닫는 괄호에 다는 주석
  • 중첩이 심하고 장황한 함수가 아니라면 의미가 없다.
  • 대신에 함수를 줄이려고 시도해보자.
• 저자를 표시하는 주석
  • 버전 관리 시스템으로 알 수 있기 때문에 필요하지 않다.
• 주석으로 처리한 코드
  • 버전 관리 시스템으로 추적할 수 있기 때문에 과감히 삭제하는 것이 좋다.
• 너무 많은 정보를 담은 주석
  • 흥미로운 역사나 관련 없는 정보

 

오늘 읽은 소감

오픈 소스나 코드를 잘 짜는 동료의 코드를 보면 주석이 거의 없었던 걸로 기억합니다.

코드에 의도를 담아서 작성하고, 불필요한 주석을 줄이는 것이 중요하다는 것을 알게 되었습니다. 

또한 주석을 달 때는 이해하기 쉽고 명료하게, 코드 자체를 설명하지 않도록 해야겠습니다.