클린 코드 Assignment #06 [4장. 주석]

TIL (Today I Learned)

2022.04.28 ~ 2022.04.29

오늘 읽은 범위

4장. 주석 (68p ~ 93p)

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

• 우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.(68p)

• 그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까?(68p)

• 좋은 주석이란?

  • 법적인 주석
    • 예를 들어 저작권 정보나 소유권 정보. 이런 주석들을 보통 소스 파일 첫머리에 들어간다.
  • 정보를 제공하는 주석
    • 하지만 함수 이름에 정보를 담아 표현하는 것이 더 낫다.
  • 의도를 설명하는 주석
    • 그냥 어떤 값이 나오는지 정보를 제공하는 것보다 이 함수 자체가 어떤 의미를 가지고 있는지 명료하게 설명한 것이 더 낫다.
    • 하지만 동시에 그릇된 주석을 달아놓을 위험이 상당히 높으므로 신중하게 고민해야 한다.
  • TODO 주석
    • 앞으로 할일을 주석으로 남겨두면 좋다.
  • 중요성을 강조하는 주석
    • 자칫하면 그냥 넘겨버릴 수 있는 코드에 강조 표시를 하면 좋다.

• 나쁜 주석이란?

  • 주절거리는 주석
    • 일단 특별한 이유 없이 의무감으로 작성한 주석. 다른 모듈, 코드를 뒤져야 이해가 되는 주석
  • 같은 이야기를 중복하는 주석
    • 코드만 봐도 충분히 파악이 가능한데 주석으로 중복 설명하는 경우
  • 오해할 여지가 있는 주석
  • 이력을 기록하는 주석
    • 소스 코드 관리 시스템이 없던 시절에는 이것이 관례였을지 몰라도 이제는 완전히 제거해야 한다.
  • 있으나 마나 한 주석
  • 주석으로 처리한 코드
    • 주석으로 코드를 처리할 경우 다른 사람들이 어떤 이유가 있어 남겨 놓았을 것이라고 생각한다. 그러므로 깨끗하게 지우는 것이 좋다.

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

오늘은 그렇게 이해가 되지 않은 문장은 없었던 것 같다. 그냥 조금 옛날 그시절 코딩 이야기가 많이 나와서 좀 신기했다 ㅋㅋ 소스 코드 관리 시스템이 없던 시절이라니... 진짜 그 시절에는 코드를 어떻게 관리했을까. 중간에 소스코드에 HTML 주석을 다는 것은 혐오 그 자체라고 한 내용이 있는데, 이런 HTML 주석은 처음 봤다.

읽으면서 제일 반영을 많이 해야 한다고 느꼈던 주석 습관은 주석으로 처리한 코드들을 잘 지워야 한다는 것이었다. 그리고 주석이 필요없도록 코드 자체에 의도를 잘 표현하는 것이 더 중요하다는 것을 배웠다.