📘클린코드 (2022.01.29) - 주석 (2)

DAY 9

오늘 읽은 범위

4장 주석 ~ p94

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

• 나쁜 주석

  • 책에 의하면 대부분의 주석은 나쁜 주석이다. 그 예를 자세히 살펴보겠다.

• 특별한 이유없이 당연한 말을 주절거리는 주석
  

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

• 코드의 동작과정을 정확히 기술하지 못한 오해할 여지가 있는 주석

• 코드 수정 이력을 기록하는 주석은 소스 코드 관리 시스템의 등장으로 필요가 없어졌다.

• 공식 문서를 복사 붙혀넣기 했을 때 딸려오는 잡음 주석

• 함수나 변수로 표현할 수 있음에도 사용하는 주석

• 닫는 블록에 주석을 달지말자. (주석이 필요 없게 함수 크기를 줄이자)

• 주석으로 처리한 코드

• HTML 주석

• 주석은 주변(같은 함수) 정보만 기술해야한다. 전역 정보 주석은 X

• 너무 많은 정보를 담은 주석

• 명확하지 않은 주석, 주석 자체가 다시 설명을 요구하면 어지럽다.

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

• 어제에 이어 상세하게 나쁜 주석의 종류를 알아보았다. 설명충의 기질이 있는 나에게 여러 뼈를 때리는 조언을 많이 해준 부분이였다. 특히 같은 이야기를 중복하는 주석과 너무 많은 정보를 담은 주석을 조심해야겠다. 생각해보면 내 주석을 읽을 때에도 약간 시간이 들었던거 같다ㅎㅎ..

• 하지만 이 책은 영어권에서 작성한 책이고 코드는 영어로 작성된다. 영어를 잘 하지 못하는 나같은 사람들은 풍부한 단어 구사 능력도 부족하고 센스있는 변수나 함수명을 짓기 힘들다. 한국에서 일하는 한 책의 내용을 맹신하는 것보단 팀원과의 소통과 회의를 통해 적당량의 주석을 사용하는것이 꼭 나쁘다 할 수 있을까?

✏ 소감 3줄 요약

• 주석을 작성할때에도 정말 필요한지 곰곰이 생각해보고 달아야겠다.
• 또한 주석이 정말 필요해서 작성하게 되면 독자의 입장에서도 정말 한번에 이해가 되는지 검토해야겠다.
• 현업을 겪어보지 못해서 정말 주석이 나쁜것인지 인정하기 힘들다. 주석을 통해 이해를 한 코드들이 꽤 많이 있기 때문에...