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

TIL (2022.01.28)

DAY 7

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

---

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

• 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

• 프로그래머에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 필요하지 않을 것이다.

• 코드만이 정확한 정보를 제공하는 유일한 출처다.

• 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라

• 좋은 주석

  • 법적인 주석: 저작권 정보, 소유권 정보, 표준 라이선스, 외부 문서 등

  • 정보를 제공하는 주석

    • (ex) 추상 메서드가 반환할 값을 설명 → but, 함수 이름에 정보를 담는다면 더 좋다

  • 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명하는 주석

  • 모호한 인수나 반환값은 그 의미를 읽기 좋게 주석으로 표현하면 이해하기 쉬워진다.

    • 하지만 그릇된 주석을 달 위험이 높기 때문에 더 나은 방법이 없는지 고민하고 주석을 달 때는 정확히 달도록 각별히 주의한다.

  • 결과를 경고할 목적의 주석

  • TODO 주석: 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무

  • 중요성을 강조하는 주석

  • 공개 API에서의 Javadocs

    • 공개 API를 구현한다면 반드시 훌륭한 Javadoc를 작성한다.

---

🤔 오늘 읽은 소감은?

• 프로그래밍을 처음 시작할 때는 주석을 잘 써야 한다는 말을 많이 들었는데, 클린 코드를 보면서 최대한 코드로 표현해서 주석을 줄여야겠다는 생각을 했다.
• 확실히 전에 이것 저것 주석을 많이 적어 놨을 때 주석을 오히려 잘 안 보게 되고, 오히려 집중력도 흩어졌던 것 같다.
• 좋은 주석에 대해 얘기하는 부분보다 나쁜 주석에 대해 얘기하는 부분이 훨씬 많다. 그만큼 주석을 쓸 때 코드로 표현할 수 있는 부분이 있는지 더 고민해보면서 신중히 주석을 작성해야겠다.