[BOOK] 클린코드, 4장 주석

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

---

< 책에서 기억하고 싶은 내용 >

• 우리는 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 주석을 사용한다.
• 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.
• 코드는 변화하고 진화한다.
  • 불행하게도 주석이 언제나 코드를 따라가지는 않는다. 아니, 따라가지 못한다.
  • 주석이 코드에서 분리되어 점점 더 부정확한 고아로 변하는 사례가 너무도 흔하다.
  • 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.
  • 부정확한 주석은 결코 이뤄지지 않을 기대를 심어준다.
• 코드만이 정확한 정보를 제공하는 유일한 출처이다.
• 주석은 나쁜 코드를 보완하지 못한다.
  • 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 코드로 의도를 표현하라!
• 좋은 주석 : 주석을 달지 않을 방법을 찾아낸 주석!
  
  • 법적인 주석 : 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보, 소유권 정보
  • 정보를 제공하는 주석
  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
  • 결과를 경고하는 주석
  • TODO 주석 : '앞으로 할 일'을 남기는 주석, 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다. 그렇지만, 주기적으로 TODO 주석을 점검해서 없애도 괜찮은 주석은 없애라.
  • 중요성을 강조하는 주석
• 나쁜 주석 :대다수 주석 (허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등)
  • 주절거리는 주석 : 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
  • 있으나 마나 한 주석
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하는 주석
  • 주석으로 처리한 코드 : 1960년대 즈음에는 주석으로 처리한 코드가 유용했지만, 현재는 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해주기 때문에, 주석으로 처리할 필요가 없다.
  • HTML 주석
  • 전역 정보
  • 너무 많은 정보
  • 모호한 관계
  • 함수 헤더

---

< 오늘 읽은 소감? 떠오르는 생각을 가볍게 적어보기 >

이제까지 코딩을 배우면서 주석에 대해서 딱히 생각해본 적이 없는 것 같다.
그냥 내가 짠 코드를 남들에게도 나에게도 설명해준다는 생각으로 주석을 달아왔었는데,
오늘 읽은 책 범위에 코드를 제대로 짜면 주석을 적을 필요가 없다는 말에 크게 한대 맞았다.
아! 그렇지! 코드를 제대로 짜면, 남들도 나도 이해가 쉽게 되니까 당연히 주석을 추가할 필요 없지!
이렇게 오늘도 하나 배웠다...! 정말 한 줄 한 줄 깊게 생각하고 정성들여서 코딩해야 하는구나ㅠ
주석을 웬만하면 달지 말고, 꼭 필요한 경우에는 좋은 주석이란 무엇인지 생각하면서 달아보자.
깊은 생각을 안 하고 살았는데... 개발자 하려니까 생각을 너무 많이 해야 한다^^
내가 하는 행동이 옳은 건지 생각 또 생각..!!

---

< 소감 3줄 요약 >

• 코드만이 정확한 정보를 제공하는 유일한 출처이다.
• 주석은 나쁜 코드를 보완하지 못한다.
• 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

---

[ 출처 : 클린 코드 ]