[Clean Code] - 4장 주석(1) 좋은 주석이란?

클린코드 68 ~ 75

도입

• 잘 달린 주석은 어떤 정보보다 유용함.
• 반대로 경솔하고 근거없는 주석은 코드를 이해하기 어렵게 만든다.
• 또한, 주석은 “순수하게 선하지” 못하며, 기껏해야 필요악 정도이다.
• 코드에 비해 주석은 오래될수록 유지보수하기 어려움 ⇒ 오류 발생 ⇒ 최대한 사용 자제
• 주석보다는 코드를 깔끔하고 이해하기 좋게 만드는 것이 최우선 과제

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

• 코드에 주석을 추가하는 일반적인 이뉴는 코드 품질이 나쁘기 때문
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드 <<<< 복잡하고 어수선하며 주석이 많이 달린 코드

코드로 의도를 표현하라!

• 코드만으로 의도를 설명하기 어려운 경우도 당연 존재

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

if(employee.isEligibleForFullBenefits())

위 두개만 비교해봐도 주석 없이 코드에 의도를 깔끔하게 반영한 것이 더 좋다.

좋은 주석

• 그럼에도 어떤 주석은 필요하거나 유익하다.
• 정말 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석

TIP)

1. 법적인 주석 - 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시
2. 정보를 제공하는 주석 - 기본적인 정보 제공(형식 제공 등)
3. 의도를 설명하는 주석 - 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.
4. 의미를 명료하게 밝히는 주석 - 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬움
5. 결과를 경고하는 주석 - 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용 ex) 런타임에 대한 경고
6. TODO 주석 - 해야할 일에 대해 남기면 프로글매이간 놓치지 않고 할 수 있다.
7. 중요성을 강조하는 주석 - 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서 주석을 사용

 

원본 노션 링크

[Clean Code] - 4장 주석(1) 좋은 주석이란?