[DAY 8] 클린 코드 TIL - 4장. 주석

TIL (2022.01.29)

DAY 8

🔖 오늘 읽은 범위 : 4장, 주석 (p.75 ~ p.94)

---

😀 책에서 기억하고 싶은 내용

• 나쁜 주석

  • 주절거리는 주석

  • 같은 이야기를 중복하는 주석

  • 오해할 여지가 있는 주석

  • 의무적으로 다는 주석

    • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.

  • 이력을 기록하는 주석

    • 예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 바람직했다. 당시에는 소스 코드 관리 시스템이 없었으니까. 하지만 이제는 혼란만 가중할 뿐이다.

  • 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석

    • 개발자가 주석을 무시하는 습관에 빠진다.

    • 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라.

  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라

  • 위치를 표시하는 주석

    • 배너를 남용하면 독자가 흔한 잡음으로 여겨 무시한다.

  • 닫는 괄호에 다는 주석

    • 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.

  • 저자를 표시하는 주석

    • 소스 코드 관리 시스템에 저장하는 편이 좋다.

  • 주석으로 처리한 코드

    • 주석으로 처리한 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어 남겼을 거라고, 중요하니까 지우면 안 된다고 생각한다.

  • HTML 주석

  • 전역 정보

    • 주석을 달아야 한다면 근처에 있는 코드만 기술하라.

    • 주석과 해당 내용 관련 코드가 떨어져 있다면 해당 코드를 수정할 때 주석까지 수정되지 않을 가능성이 높다.

  • 너무 많은 정보

  • 모호한 관계

    • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.

  • 함수 헤더

    • 짧은 함수는 긴 설명이 필요 없다.

  • 비공개 코드에서 Javadocs

    • 공개 API는 Javadocs가 유용하지만 공개하지 않을 코드라면 Javadocs는 쓸모가 없다.

---

🤔 오늘 읽은 소감은?

• 주석을 달기 전에 꼭 주석으로 설명해야만 하는 내용인지 한번 더 고민하자.
• TODO 주석을 달아 놓은 부분은 그냥 방치하지 말고 여력이 될 때 바로 구현하자!
• 전에 누가 수정했는지, 언제 수정했는지 주석을 남긴 적이 있는데, 확실히 소스 코드 관리 시스템을 쓰면 해결될 부분이다. 시대가 변하면서 좋은 코드의 기준도 점점 달라져 가는 것 같은 점이 흥미롭다.

---

🧐 궁금한 내용이 있거나, 잘 이해되지 않는 내용

• Javadocs가 비공개 코드에서는 필요 없다고 하는데 팀 내부에서만 사용할 거지만 프론트에서는 백엔드 쪽에서 API 명세를 문서화해줬으면 하는 필요를 느낄 수 있다. 이 경우에도 불필요하다고 말할 수 있을까?