클린코드 TIL (4장)

TIL (Today I Learned) 날짜

2022.04.29 (금)

오늘 읽은 범위

4장 주석

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

• 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
• 코드로 의도를 표현할 수 있다면 주석은 거의 필요하지 않다.
  • 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.
• 주석이 문제가 되는 이유는 주석을 유지/보수하는 게 현실적으로 불가능하기 때문이다.
• 코드는 개선을 통해서 이리저리 옮겨지지만 주석이 언제나 코드를 따라가는 것은 아니다.
• 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 코드에 의도를 표현하라.
• 그렇다면 좋은 주석은 어떤 주석일까?
  • 정보를 제공하는 주석
    • 주석이 있어 알고리즘 이해가 쉬운 경우
  • 의도를 설명하는 주석
  • 결과를 경고하는 주석
  • TODO 주석
    • 주기적으로 점검해서 없애도 될 경우 없애기
  • 중요성을 강조하는 주석
• 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
• 나쁜 주석
  • 주석이 있음에도 이해가 안되어 다른 코드를 뒤져봐야 하는 경우
  • 코드보다 읽기가 힘든 경우
  • 의무적으로 다는 경우
  • 있으나 마나 한 경우
    • 너무 당연한 사실을 언급한다.
  • 코드를 주석처리한 경우
    • 독자로 하여금 이유가 있거나 중요해서 남겨놓았을 거라는 불필요한 추측을 하게 만든다.
  • 비공개 코드에서는 Javadocs를 사용하는 경우
    • Javadocs 주석이 요구하는 형식으로 인해 코드가 산만해진다.
• 주석을 통해 무엇을 전달하고자 하는지, 독자가 어떤 정보를 얻길 바라는지 생각하기.
• 주석이 올바른지 검증하기가 쉽지 않기 때문에 위험한 결과를 초래하기도 한다.
• 주석을 달아야 한다면 근처에 있는 코드만 기술하라.
• 비공개 코드에서는 Javadocs를 사용하지 마라

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

• 리팩터링 작업을 하다가 JSdoc을 처음 사용하게 되었다. 사용성에 엄청 만족해서 여기저기에 사용해야겠다고 다짐했는데 주석 파트를 읽으면서 JSdoc과 기본 주석을 잘 분류해서 사용해야겠다는 생각이 들었다. 회사에서 나쁜 주석이라 말하던 케이스에 딱 맞게 내가 사용하고 있었기 때문이다. 책을 읽으면서 이게 과연 최선일까? A와 B 중에 어떤 방식이 더 나은 방법일까를 고민하는 시간을 충분히 가져야 한다는 걸 배웠다. 나의 선택에 대한 근거를 좀 더 자세히 정리해봐야겠다.