[SW 유지보수성 향상을 위한 Clean Code] Clean Comment

✨ 이 글은 [ 코드프레소 Java 웹 개발 체험단 활동 ] 내용입니다 ✨

💜 코드프레소 이러닝 강의 수강 중 - SW 유지보수성 향상을 위한 Clean Code 💜

😎 아래의 링크를 통해 프리미엄 IT 교육 서비스, 코드프레소를 확인해보세요 😎

https://www.codepresso.kr/

프리미엄 IT 교육 서비스 - 코드프레소

---

Comment (주석)

• Comment는 Code에 대한 사람이 읽을 수 있는 부가 설명이다
• 사람이 Code를 더 쉽게 이해할 수 있게 하는 것이 목적이다
• 일반적으로 Compiler/Interperter는 Comment를 실행하지 않고 무시한다

 

 

Clean Comment Principle

• Comment는 필요악이다
• Comment는 대부분의 상황에서 사용하지 말아야 한다
• 그러나 Comment를 사용해야 하는 몇 가지 예외 상황이 있다

 

 

Comment보다 Code 그 자체가 의미가 있어야 한다

• Comment로 부가 설명이 필요하면 Code가 충분히 의미있지 못하다는 것이다
• 의미있는 이름, 명확한 Code는 어렵고, Comment는 쉽다
• Comment에 의지하기 보다 의미 있는 Code를 작성하는 노력이 필요하다

 

 

Comment는 최신 정보를 담지 못한다

• 처음 신규 코드를 작성할 때에는 Comment도 정성스럽게 작성한다
• 하지만 Code가 바뀌면 Comment도 같이 변경하지 않기도 한다
• 따라서 Comment의 정보는 잘못된, 오래된 정보를 담고있을 가능성이 높다

 

 

Comment는 불필요하고 중복된 정보를 포함한다

• Code로 의미를 표현하고 있는 경우에는 Comment는 필요없는 중복 정보가 된다!
• 코드의 수정 이력을 표현하는 Comment - 형상 관리 도구로 충분히 정보를 담을 수 있다!

 

---

Bad Comment

 

의미가 모호한 코드를 설명하는 Comment

• Code 자체로 충분히 명확한 표현이 안될 때
• 가독성 향상을 목적으로 Comment를 작성한다
• 하지만 이 경우에는 Code 자체를 개선해야 한다!

 

 

중복된 정보를 나타내거나 의무적으로 작성하는 Comment

• 의미가 분명한 Code에 Comment로 중복 설명
• 중복은 제거해야 마땅하다
• Code 변경 시 Comment는 변경되지 않을 가능성도 존재한다

 

 

Comment 처리 된 Code

• 필요는 없지만 당장 없애기는 아까운 Code
• Git과 같은 형상 관리 도구로 얼마든지 관리가 가능하다!

 

 

 

이력을 남겨놓은 Comment

• 특정 파일이나 Class, Method에 수정 이력을 Comment로 남겨둔다
• 형상관리 도구가 보편적이지 않던 시절에는 가능했다
• 현재는 형상 고나리에 모든 이력이 관리되기 때문에 모든 이력 Comment는 무조건 삭제해야 한다!

 

 

99%의 Comment는 불필요하다!

• 다양한 Bad Comment의 유형이 있다
• 기억해야 할 1가지는 Comment는 Code Bad Smell이라는 점이다!

 

---

Clean Comment

 

Comment를 사용하지 않는 것!

• Comment를 사용하지 않는 것이 최고의 Clean Comment이다
• 진실은 오직 동작하고 있는 Code에만 존재한다
• Code로 의미를 표현해야 한다
• Comment가 필수적인 예외 상황은 많지 않다

 

 

저작권 등을 명시하는 Comment

• 회사의 정책에 의해 소유권, 저작권 등을 표시해야 하는 경우가 있다
• 모든 소스 파일에 저작권을 표시하는 Comment가 필요하다

 

 

다수가 사용하는 Open API의 문서화

• 오픈소스 라이브러리는 API 사용의 용이성을 높이기 위해 Java Doc과 같은 Comment가 필요하다
• 하지만 회사 내부나 규칙을 아는 사람들만 보는 코드의 경우에는 굳이 달 필요 없다

 

 

이름만으로 충분히 의미를 전달하기 어려운 경우

• 최대한 이름으로 의미를 표현한다
• 하지만 불가피하게 이름만으로 충분한 의미/의도를 표현하지 못하는 경우에는 주석을 달아도 된다
• 대표적인 사례로 복잡한 정규 표현식의 의도를 표현한다

 

 

TO DO Comment

• TO DO Comment로 앞으로 해야할 작업을 간략히 표시가 가능하다
• 최근 IDE 들이 TO DO Comment를 인식해서 잊을 가능성이 적다
• 주기적으로 TO DO Comment를 확인할 필요가 있다

---

Summary : Clean Comment

• Comment는 기본적으로 Bad Smell이다
  • Code로 충분히 의미를 설명하지 못한다
  • 불필요하고 중복적인 정보를 제공할 가능성이 높다
  • 잘못된 정보를 제공하기도 한다
• Comment를 가급적 피하고 Code로 의미를 표현해야 한다
• Clean Comment 예외 상황에는 적절한 Comment 사용이 필요하다