[클린코드] TIL - 4장 주석

🧡  TIL

주석은 필요악이다.
주석은 오래될 수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 주석을 유지하고 보수하기란 현실적으로 불가능하다.

 

• 주석은 나쁜코드를 보완하지 못한다.
  -> 주석을 작성할 시간에 코드를 정리하는 편이 낫다.
  -> 가능한한 코드로 의도를 표현하라.

// as-is
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if(emplyee.flags & HOURLY_FLAG) && (emplyee.age > 65))


// to-be
if(employee.isEligibleForFullBenefits())

• 좋은 주석
  • 법적인 주석(copy rights)
  • 정보를 제공하는 주석 (추상 메서드의 반환값 등)
  • 의도를 설명하는 주석 (compareTo 등 이해가 어려운 코드에 한해)
  • 결과를 경고하는 주석 (특정 테스트 케이스를 경고)
  • TODO 주석
  • 중요성을 강조하는 주석
• 나쁜 주석
  • 주절거리는 주석 (이해가 어렵고 모호한 주석)
  • 같은 이야기를 반복하는 주석 (코드와 같은 이야기를 하는 주석)
  • 의무적으로 다는 주석 (모든 변수에 주석을 달아야 한다 같은 불 필요한 규칙으로 생긴 주석)
  • 이력을 기록하는 주석, 저자 표시하는 주석 (소스 코드 관리 시스템의 존재로 불필요함)
  • 있으나 마나 한 주석 (너무 당연한 사실 언급 eg. 기본생성자)
  • 무서운 잡음
  • 닫는 괄호에 다는 주석 (함수 내의 내용이 많아져서 발생하는 주석. 함수의 내용을 줄이려 노력하기)
  • 전역 정보 (주석은 근처에 있는 코드에 대해서만 기술. 코드가 변하면 주석과 다른 정보를 줄 수 있음)
  • 주석으로 처리한 코드 (소스 관리 시스템으로 필요가 없다. 잃어버릴 염려말고 버리기)
  • HTML 주석
• 올바른 주석 작성법
  • 주석과 주석이 설명하는 코드는 명백해야 함
  • 함수 헤더 -- 짧은 함수는 주석말고 이름으로 잘 표현하기

🩵  오늘 읽은 범위

4장 주석

💜  기록

 

톰캣이나 Javadocs에서도 주석을 깨끗하게만 사용하는 것은 아님
-> 아무래도 정보 제공성이 높다 보니 그럴듯

 

회사 코드를 작성할 때 private method 를 팀 내에서 썩 좋아하는 문화는 아니라서 함수로 빼기보다는 주석을 많이 달았다. 이런 모양새가 이번 장에서 이야기하는 나쁜 주석의 좋은 예시라는 생각이 들었다. 함수로 빼기를 탐탁치 않아했던 이유는, 코드의 내용이 다른 곳에 분산되어 있기 때문에 주요 로직이 잘 보이지 않을 수 있다는 이유에서였다. 함수를 사용하되 주요 로직이 잘 보이게 하는 방식에 대해, 불 필요한 주석을 지양하는 방법에 대한 고찰이 필요할 듯 보인다.

 

 

🤍 나의 최애 북틸

1️⃣ lactofree

javascript 예시를 직접 찾아서 공유를 해주셔서 감사합니다.

https://nomadcoders.co/community/thread/9970

[클린 코드] TIL 3장. 함수 – 노마드 코더 Nomad Coders

 

2️⃣ ppaa1135

https://nomadcoders.co/community/thread/9965

switch문을 썼던 과거의 사례를 언급했는데 공감이 갔다.

 

3️⃣ rhxogns13

https://nomadcoders.co/community/thread/9962

깔끔한 내용 정리