< Clean Code > Day 8~9

Day 8~9

🔖 오늘 읽은 범위: 4장 주석

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

• "나쁜 코드에 주석을 달지 마라. 새로 짜라."
• 주석은 쉰들러 리스트가 아니다. 주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다.
• 코드로 의견을 표현하라.

좋은 주석(필요악)

• 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다.
• 가능하면 함수 이름에 정보를 담는 편이 더 좋다.
• 때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.
• 때로는 '앞으로 할 일'을 //TODO 주석으로 남겨두면 편하다.
• 자칫 대수롭지 않다고 여겨길 뭔가의 중요성을 가종하기 위해서도 주석을 사용한다.

나쁜 주석(대부분의 주석)

• 특별한 이유 없이 의무감으로 혹은 프ㄹ세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비다.
• 헤더에 달린 주석이 같은 코드 내용을 그대로 중복한다.
• 예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 바람직했다. 당시에는 소스 코드 관리 시스템이 없었으니까. 하지만 이제는 혼란만 가중할 뿐이다.
• 너무나 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석.
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라.
• 배너 아래 특정 기능을 모아놓으면 유용한 경우도 있긴 하다. 하지만 일반적으로 가독성만 낮추므로 제거해야 마땅하다. 특히 뒷부분 슬래시(/) 로 이어지는 잡음. // Action //////////
• 공로를 돌리거나 저자를 표시하는 주석
• 주석으로 처리한 코드: 그냥 코드를 삭제하라.
• HTML 주석: 주석처리한 html 코드는 혐오 그 자체다.
• 전역 정보: 주석을 달아야 한다면 근처에 있는 코드만 기술하라. 시스템의 전반적인 정보를 기술하지 마라.
• 너무 많은 정보: 관련 없는 정보를 장황하게 늘어놓지 마라.
• 모호한 관계: 주석과
• 함수 헤더: 짧은 함수는 긴 설명이 필요 없다.
  
  

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

주석은 '필요악'이며 가능한 코드로 표현하라!, 는 주석에 관한 저자의 단호한 의견을 알게 된 장이었다.

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

x

소감 3줄 요약

• "나쁜 코드에 주석을 달지 마라. 새로 짜라."
• 주석은 쉰들러 리스트가 아니다. 주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다.
• 코드로 의견을 표현하라.