📘클린코드 (2022.01.28) - 주석 (1)

DAY 8

오늘 읽은 범위

4장 주석 ~ p75

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

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

• 잘 달린 주석은 유용할 수 있지만 주석은 기껏해야 필요악이다.

  • 주석을 필요로 한다면 그것은 우리가 코드로 의도를 표현하지 못한 것이다.

• 주석은 오래될수록 코드에서 멀어지고 오래될수록 그릇될 가능성도 커진다.

  • 프로그래머들이 주석까지 유지보수를 하기란 현실적으로 불가능 하기 때문에..

• 부정확한 주석은 없는 주석보다 훨씬 나쁘다.

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

  • 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. (설명이 필요한 코드)
  • 난장판을 주석으로 설명하려 하지말고 깨끗히 정리해야한다.

• 코드로 의도를 표현하라

• 좋은 주석

  • 법적인 주석
    • 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣어야 할때가 있다.
  • 정보를 제공하는 주석
    • 정규표현식의 결과 형식 또는 파일 형식등 코드로 표현하기 어려운 내용
  • 의도를 명료하게 밝히는 주석
    • 인수나 반환값이 표준라이브러리나 변경하지 못하는 코드일 경우 주석으로 의도를 명료히 밝힐 필요가 있다.
      (이때 주석이 그릇된 의미를 전달할 경우를 조심하자.)
  • 결과를 경고하는 주석
    • 때로는 코드 실행에 주의점을 명시하는 주석은 도움이 될 수 있다.
  • TODO 주석
    • 당장 구현하기 어려운 업무, 도움을 요청하는 코드, 필요없어지면 삭제하길 권고하는 코드등을 TODO 주석을 통해 관리하면 편리하다.
    • 하지만 TODO를 너무 남발해선 안되고 주기적으로 점검해 관리해야한다.
  • 중요성을 강조하는 주석

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

• 나는 주석을 자주 다는 편이다. 이게 다음에 코드를 읽을 때에도 좋고 누군가 나의 코드를 읽을 때에도 편하게 읽을 수 있다고 생각해서였다. 그래서 처음 책을 봤을땐 약간 거부감이 들기도 했다.
  하지만 내용을 살펴보니 납득이 갔다. 나의 짧은 코드들이 아닌 실무의 프로젝트에서는 주석들을 작성해도 코드는 계속해서 추가되고 삭제된다. 즉 이전의 주석이 이후의 코드를 설명하지 못하고 오히려 잘못된 내용을 전달 할 수 있다는 것이다.
  또한 이전 장에서 계속해서 배운 의미 있는 이름을 잘 지으면 책의 말대로 주석이 필요없을것 같다. 주석을 줄여보자.

✏ 소감 3줄 요약

• 이전까진 주석이 안좋다는 생각을 갖지 못했는데 좋은 공부가 돼었다.
• 주석 없이도 의도가 이해가 가는 코드를 작성하자
• 주석은 나쁜 코드를 보완하지 못한다.