[Book][Clean Code][TIL] 책 리뷰 04

Clean Code 클린코드 TIL(Today I Learned) 2022.02.25

📖 DAY 4

📝 오늘 읽은 범위

4장. 주석

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라. (p.68)
• 주석은 언제나 실패를 의미한다.
• 불행하게도 주석이 언제나 코드를 따라가지는 않는다. 아니, 따라가지 못한다.
• 하지만 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다. (p.69)
• 부정확한 주석은 아에 없는 주석보다 훨씬 더 나쁘다. 부정확한 주석은 독자를 현혹하고 오도한다. 그러므로 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.(p.70)
• ⭕️ 좋은 주석 (정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석)

  • 법적인 주석 : 회사가 정립한 구현 표준에 마주처 법적인 이유로 특정 주석을 명시 ( 예- 저작권 정보, 소유권 정보 등)
  • 정보를 제공하는 주석 (함수 이름에 정보를 담는 편이 더 좋다)
  • 의도를 성명하는 주석
  • 의미를 명료하게 밝히는 주석 (더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의 필요
  • 결과를 경고하는 주석
  • TODO 주석 (‘앞으로 할 일’ 명시, 주기적으로 TODO 주석을 점검해 없애도 되는 주석은 없애는 것을 권함)
  • 중요성을 강조하는 주석
  • 공개 API에서 Javadocs

• ❌나쁜 주석 ( 대다수 주석 ) (p.75)

  • 주절거리는 주석 (특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 다는 주석)
  • 같은 이야기를 중복하는 주석 (코드보다 주석을 읽는 시간이 더 오래 걸릴 수 있다.)
  • 오해할 여지가 있는 주석 (살짝 잘못된 정보)
  • 의무적으로 다는 주석 (코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래)
  • 이력을 기록하는 주석 (완전히 제거하는 것이 좋음)
  • 있으나 마나 한 주석 (너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석)
  • 무서운 잡음

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

  • 위치를 표시하는 주석 (반드시 필요할 때만 명시)
  • 닫는 괄호에 다는 주석 (주석 대신 함수를 줄이려 시도해라)
  • 공로를 돌리거나 저자를 표시하는 주석 (쓸모없는 정보가 될 확률 높음)
  • 주석으로 처리한 코드 (다른 사람이 지우기를 주저하여 쓸모 없는 코드가 쌓인다)
  • HTML 주석
  • 전역 정보 (주석을 달아야 하면, 근처에 잇는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.)
  • 너무 많은 정보
  • 모호한 관계 (주석과 코드는 둘 사이 관계까 명백해야 한다.)
  • 함수 헤더 (짧은 함수는 긴 설명이 필요 없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.)
  • 비공개 코드에서 Javadocs (공개하지 않을 코드라면 쓸모가 없다.)

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

• 지금까지 난 오히려 주석으로 상세하게 설명하는 것이 이 코드를 읽을 사람에게 좋을 거라고 생각해서 조건문, 함수 호출 시 등 모두 주석을 달아왔다. 이 책을 읽고 나니 이렇게 주석을 달 시간에 함수이름으로 의도를 표현하고, 코드를 위에서 아래로 가독성이 좋도록 구현하는 것이 더 나았을 것 같다는 생각이 든다.
• 나쁜 코드의 예로 ‘주석으로 처리한 코드’가 나왔을 때, 뜨끔했다.ㅎㅎ 코드를 구현할 때, 여러가지 방식으로 시도하다가 최종적으로 선택한 코드를 제외하고 나머지 코드 중 괜찮은 코드를 주석으로 남겨놓는 경우가 있었다. 앞으로는 선택된 코드 외에 다른 코드는 지우도록 해야겠다!!

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

#코딩 #개발자 #노마드북클럽 #노개북 #clean_code