[클린 코드] 4장 - 주석

 

나쁜 코드에 주석을 달지 마라. 새로 짜라
- 브라이언 W. 커니핸, P.J. 플라우거

 

잘 달린 주석은 유용하지만 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만들어요. 주석은 '순수하게 선하지' 못해요. 프로그래밍 언어 자체가 표현력이 충분하다면 주석은 전혀 필요하지 않아요.

그래서 주석이 필요한 상황에 처하면 곰곰이 생각해야 해요. 상황을 역전해 코드로 의도를 표현할 방법은 없을지. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 해요. 

 

나의 생각: 코드로 표현할 수 있는 것을 주석으로 표현하려고 시도하는 것은 문제가 있을 수 있어요. 하지만 현업 코드를 작성하며 분명히 도움 받았던 주석들도 있었어요. 네트워킹 시 받아올 JSON의 형태를 Entity에 주석으로 마킹할 경우 코드를 읽기 한결 수월하고 오히려 코드의 잘못된 부분이 없는지 확인할 수 있었어요. 프로젝트가 커질수록 필요한 JSON이 많아지고, 이를 문서화하다 보면 문서 역시 사이즈가 커졌어요. 그래서 코드에 간단히 주석처리함으로써 훨씬 코드를 읽는데 수월해졌어요. 물론 잘 쓴 코드라면 주석이 없이도 JSON의 모양을 알 수 있어야 하지만, 반대로 여러 사람이 협업하는 프로젝트에서는 내가 짠 코드가 아닐 경우 JSON의 모양을 보고 코드를 리뷰할 수 있어서 좋았던 것 같아요. 변경 사항이 생길 경우도 훨씬 직관적으로 이해할 수 있었던 것 같아요. 단, 코드가 통과하는 것만을 목표로 수정 시 코드만 수정하는 게 아니라 관련 주석을 반드시 같이 수정해야 하는 건 기본이고, 이건 팀에서 코드 리뷰 시 함께 신경 쓸 수 있을 것 같아요. 주석 역시도 팀에서 정할 컨벤션의 영역이지 무조건 무시할 필요는 없는 것 같아요.

 

😊 좋은 주석

 

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이에요. 지저분한 모듈임을 자각할 경우 주석을 다는데 이것보다는 코드를 정리하는게 더 좋아요.

 

2. 코드로 의도를 표현하라.

많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분해요.

 

3. 좋은 주석

• 법적인 주석
  저작권 정보와 소유권 정보는 회사에 따라 필요할 수 있어요. 
  e.g. Copyright (C)...
• 정보를 제공하는 주석
  기본적인 정보를 제공하는 주석은 편리할 수 있어요. 
  e.g. // 테스트 중인 Responder 인스턴스를 반환

4. 의도를 설명하는 주석

구현을 이해하게 도와주는 것을 넘어서 결정에 깔린 의도까지 설명할 수 있어요.

 

나의 생각: 코드의 의도는 되도록 PR 메세지에 담으려고 했었어요. 코드에 의도까지 설명하는 건 오히려 무의미하게 코드 줄 수를 늘린다고 생각해요. Xcode의 경우 Merge 된 PR의 이름을 확인할 수 있고, 의도를 알고 싶다면 충분히 검색을 통해(혹은 Jira 등으로) 코드의 의도를 알 수 있다고 생각해요. 그만큼 코드를 작성하는 사람이 PR 메시지나 Commit 메시지, Jira 등의 협업 툴에 공을 들이는 게 나중을 위해 좋은 것 같아요.

 

5. 의미를 명료하게 밝히는 주석

애매모호한 인수나 반환값은 주석을 통해 부연이 가능해요. 특히 표준 라이브러리나 변경하지 못하는 코드에 속할 때 명료하게 밝히는 주석이 유용해요.

 

나의 생각: 이 부분이야 말로 적절한 네이밍이나 코드를 통해 해결할 수 있다고 생각해요.

 

6. 결과를 경고하는 주석

다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용해요. 예를 들어, 특정 테스트 케이스를 꺼야 하는 이유를 설명하는 주석이에요.

e.g. // 여유 시간이 충분하지 않다면 실행하지 마십시오. -> JUnit의 경우 @Ignore로 끌 수 있어요.

        // 객체가 Thread Safe하지 못하므로 인스턴스를 독립적으로 생성해야 한다.

 

나의 생각: 어차피 Xcode는 테스트 메소드메서드 단위로 테스트가 가능하기 때문에 굳이 이럴 필요가 없고, 유난히 한 가지 메서드가 테스트가 오래 걸린다면 그 테스트 메서드의 설계가 부족했던 걸 수 있다고 생각해요. 또한 Thread Safe하지 못해 인스턴스를 독립적으로 생성해야 하는 문제 역시 PR 리뷰를 통해 충분히 대화하고 기록할 수 있다고 생각해요. 이렇게 발생할 수 있는 문제 상황에 대해서는 항상 PR 리뷰에서 충분히 대화했던 것 같아요. 굳이 주석을 달아야 하나 생각되는 부분이에요.

 

7. TODO 주석

앞으로 할 일을 //TODO 주석으로 남기면 편해요. 다만, 나쁜 코드를 남겨두는 핑계가 되어서는 안되요.

 

나의 생각: 가장 활용도가 높은 주석인 것 같아요. 특히 Xcode는 TODO, MARK, FIXME를 사용하는데 정말 유용했던 것 같아요. Jira에서 티켓을 산정할 때, 티켓의 사이즈가 너무 커져서 연결되는 작업으로 끊어서 작업할 경우가 있었어요. 이런 경우, 뒤에서 이어서 할 작업을 동료들은 이해하지 못하고 코드가 불완전하거나 잘못된 것으로 이해할 수 있기 때문에 주석을 통해서 설명하는 게 매우 중요하다고 생각돼요. 다만 해야 할 작업이 너무 오래 남지 않게 주기적으로 관리하면 더 좋을 것 같아요.

 

8. 중요성을 강조하는 주석

자칫 가볍게 여겨질 뭔가의 중요성을 강조하는데 주석을 사용해요.

 

🥲 나쁜 주석

1. 주절거리는 주석

특별한 이유 없이 의무감으로 혹은 프로세스에서 시켜서 마지못해 주석을 다는 경우예요.

 

2. 같은 이야기를 중복하는 주석

헤더에 달린 주석이 같은 코드 내용을 그대로 중복하는 경우 코드보다 주석을 읽는데 시간이 더 걸릴 수도 있어요.

아래 코드의 주석은 불필요한 3줄이 추가되었어요.

/**
 * 컨테이너와 관련된 Manager 구현
 */
 let manager: Manager = Manager()

 

3. 오해할 여지가 있는 주석

주석이 엄밀하지 못해 '살짝 잘못된 정보'를 갖게 된다면 다른 프로그래머가 그 코드를 오해할 수 있어요.

 

4. 의무적으로 다는 주석

이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래해요.

 

5. 이력을 기록하는 주석

일종의 로그를 기록하는 주석으로 어떤 사람들은 모듈을 편집할 때마다 주석을 추가해요. 예전에는 이러한 관례가 바람직했지만 지금은 소스 코드 관리 시스템이 있으니까 이제는 이런 주석은 지양해야 해요.

 

6. 있으나 마나 한 주석

너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이에요. 이런 주석은 지나친 참견이라 개발자가 주석을 무시하는 습관에 빠질 수 있어요.

/** 월 중 일자 */
private let dayOfMonth: Int

 

7. 위치를 표시하는 주석

위치를 표시하기 위해 무의미한 주석을 다는 것은 좋지 않아요. 특히 뒤에서 '/'를 반복하는 것은 좋지 않아요.

// Actions ////////////////////////////////////

나의 생각: Xcode는 위에서 언급한 //MARK로 위치 표시가 가능하기 때문에 큰 의미는 없는 것 같아요.

 

8. 닫는 괄호에 다는 주석

때로는 프로그래머들이 닫는 괄호에 주석을 달아요. 중첩이 심하고 장황한 함수면 모르지만 작고 캡슐화된 함수에는 잡음이에요.

 

나의 생각: 알고리즘 문제를 풀 때 주석이 필요한 경우 줄 수를 줄이는 것 역시 중요해서 습관적으로 닫는 괄호 옆에 주석을 달았던 것 같아요. 가능하면 주석을 줄이지만 꼭 필요한 경우 헤더에 달거나 채워져야 할 코드 빈 공간에 주석을 다는 습관을 가지는 게 좋을 것 같아요.

 

9. 주석으로 처리한 코드

주석으로 처리한 코드만큼 밉살스러운 관행도 드물어요. 주석으로 처리된 코드는 다른 사람들이 지우기를 주저해요. 이유가 있어서 남겨놓은 느낌이 들기 때문이에요.

 

나의 생각: 현업 코드에서 다른 동료들이 남겨놓은 주석 처리된 코드들을 봤어요. 확실히 그런 코드는 손대기 어려운 것 같아요. 다만, 빠른 시간에 많은 일을 처리해야 하는 환경의 경우 필요한 작업일 수 있을 것 같아요. 예를 들어, 그로쓰 작업이라 단기적 실험으로 작업하는 경우 코드를 다른 곳에 옮겨놓기는 애매한데 이런 경우는 주석처리해놓고 팀원들과 소통하는 것이 팀원들도 그 코드를 이해하는데 더 빠를 수 있을 것 같아요. 주석으로 모든 설명을 해두는 것보다 코드로 읽는 게 더 빠른 경우도 있을 수 있을 것 같아요.

 

10. HTML 주석

HTML 코드를 주석으로 처리하는 건 매우 안 좋아요.

 

11. 전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술해요. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하면 안돼요.

 

12. 너무 많은 정보

주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓으면 안돼요.

 

13. 모호한 관계

주석 자체가 다시 설명을 요구하는 건 주석을 잘못 단 것이에요. 주석의 목적은 코드를 보충 설명하기 위해서인데 그 보충 설명이 추가 설명을 필요로 하면 안돼요. 

e.g. 정수 등의 숫자에 대한 설명 없이 그 숫자의 의미를 알고 있는 작성자가 의미만 주석으로 달아 놓는다면, 이 주석을 읽는 다른 사람은 그 숫자와 의미가 매칭 되지 않아 주석을 이해하지 못할 수 있어요.

 

 

 

 

클린코드(Clean Code) by Robert.C.Martin