클린 코드 (Clean Code) - 4장 주석

노션 정리

4장 주석

 

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라.
• 브라이언 W. 커니핸, P.J.플라우거
• 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다.
• 코드는 언제나 변한다. 주석이 언제나 코드를 따라가지 않는다. 부정확한 주석은 아예 없는 주석보다 나쁘다.
• 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 주석을 가능한 줄이도록 노력해야한다.

주석은 나쁜 코드를 보완하지 못한다.

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

코드로 의도를 표현하라!

• 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

좋은 주석

• 법적인 주석
  • 때로는 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시한다.
  • 소스 파일 첫 머리에 들어가는 주석이 반드시 계약 조건이나 법적인 정보일 필요는 없다. 모든 조항과 조건을 열거하는 대신에, 가능하다면, 표준 라이선스나 외부 문서를 참조해도 되겠다.
• 정보를 제공하는 주석
  • 기본적인 정보를 주석으로 제공하면 편리하다.
  • 때때로 이런 주석이 유용하다 할지라도, 가능하다면 함수 이름에 정보를 담는 편이 더 좋다.

  // kk:mm:ss EEE, MMM dd, yyyy 형식이다.
  Pattern timeMatcher = Pattern.compile(
  	"\\\\d*:\\\\d*:\\\\d* \\\\w*, \\\\w* \\\\d*, \\\\d*");
  

  • 이왕이면 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 좋고 더 깔끔하겠다.
• 의도를 설명하는 주석
  • 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.
• 의미를 명료하게 밝히는 주석
  • 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다. 일반적으로 인수나 반환값 자체를 명확하게 만들면 더 좋겠지만 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
• 결과를 경고하는 주석
  • 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.
• TODO 주석
  • ‘앞으로 할 일'을 //TODO 주석으로 남겨두면 편하다.
  • 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.
• 중요성을 강조하는 주석
  • 자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용한다.
• 공개 API에서 Javadocs
  • 설명이 잘 된 공개 API는 유용하다.

나쁜 주석

• 주절거리는 주석
  • 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
• 같은 이야기를 중복하는 주석
  • 자칫하면 코드보다 주석을 읽는 시간이 더 오래 걸린다.
  • 코드만 지저분하고 정신 없게 만든다.
• 오해할 여지가 있는 주석
  • ‘살짝 잘못된 정보’로 인해 혼란을 일으킬 수 있다.
• 의무적으로 다는 주석
  • 코드만 헷갈리게 만들며, 거짓말할 가능성을 높이며, 잘못된 정보를 제공할 여지만 만든다.
• 이력을 기록하는 주석
  • 혼란만 가중할 뿐이다. 완전히 제거하는 편이 좋다.
• 있으나 마나 한 주석
  • 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.
• 무서운 잡음
  • 때로는 javadocs도 잡음이다.
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
  • 일반적으로 위와 같은 주석은 가독성만 낮추므로 제거해야 마땅하다. 특히 뒷부분에 슬래시(/)로 이어지는 잡음은 제거하는 편이 좋다.
• 닫는 괄호에 다는 주석
  • 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.
• 공로를 돌리거나 저자를 표시하는 주석
  • 소스 코드 관리 시스템에 저장하는 편이 좋다.
• 주석으로 처리한 코드
  • 소스 코드 관리 시스템에 코드를 기억한다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다.
• HTML 주석
  • 편집기 / IDE에서조차 읽기가 어렵다.
• 전역 정보
  • 주석을 달아야 한다면 근처에 있는 코드만 기술하라.
  • 코드 일부에 주석을 달면서 시스템 전반적인 정보를 기술하지 마라.
• 너무 많은 정보
  • 주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.
• 모호한 관계
  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
• 함수 헤더
  • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
• 비공개 코드에서 Javadocs
  • 공개 API는 Javadocs가 유용하지만 공개하지 않을 코드라면 Javadocs는 쓸모가 없다.

 

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

• 주석에 이렇게 신경써야할 게 많다는 걸 알게 되었다.
• 주석을 쓰지 않는 게 무조건 좋다고 생각을 했지만 주석을 추가함으로써 더 좋은 정보를 제공할 수 도 있다는 걸 깨달았다.
• 어떤 주석이 좋은 주석인지 또 어떤 주석이 나쁜 주석인지 알게 되었고 앞으로 코드에서 최대한 주석을 없애도록 노력하겠지만 좋은 주석이 존재한다는 걸 생각하면서 작성해야겠다.

 

 

 

 

 

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

• 나쁜 주석 - 주절거리는 주석 (p76)