주석은 쓰지 않는 것이 좋다.
주석이 오래되면 코드와 달라질 수 있고, 모든 주석을 관리할 수는 없다.
주석이 없어도 한 눈에 알아볼 수 있는 소스를 작성하는 것이 좋다.
// 직원에게 복지 혜택을 받을 수 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
vs
if employee.isEligibleForFullBenefits())
몇초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다.
그럼에도 주석이 필요한 경우들이 있다.
- 1. 법적인 주석 : 각 소스 파일 첫 머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다.
- 2. 정보를 제공하는 주석 : 기본적인 정보를 제공하는 주석은 편리할 수 있다.
- 3. 의도를 설명하는 주석 : 구현을 이해하게 도와주는 것을 넘어서 결정에 깔린 의도까지 설명할 수 있다.
때때로 구현을 이해하는데 편하게, 구현 의도를 설명해야 되는 때가 있다. 그럴 경우는 보통은 PR을 통해서 코드 리뷰때 설명하면 되기에 굳이 주석으로 남겨야되나 싶다. PR도 기록된 문서로 볼 수 있기 때문이다.
- 4. 의미를 명료하게 밝히는 주석 : 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
이 부분은 앞에 "코드로 의도를 표현하라" 의 내용처럼 코드로 표현해야 된다고 생각한다. Swift API GuildLines 에서도 언급하는데, 전달인자를 통해서 모호한 인수를 더 이해하기 좋게 표현하라고 언급하고 있다.
- 5. 결과를 경고하는 주석 : 다른 동료에게 결과를 경고할 목적으로 주석을 사용한다. 예를 들어, 특정 테스트 케이스를 꺼야 하는 이유를 설명하는 주석이 있다.
e.g. // 여유 시간이 충분하지 않다면 실행하지 마십시오. -> JUnit의 경우 @Ignore로 끌 수 있어요.
// 객체가 Thread Safe하지 못하므로 인스턴스를 독립적으로 생성해야 한다.물론 Xcode 에서 테스트 케이스의 경우 각 테스트 메서드마다 테스트가 수행되기 때문에 이렇게 할 필요는 없지만, 결과를 경고해야 되는 이유가 있다면 해당 경우는 주석을 남기는 것이 나빠보이지는 않는다. 허나, 주석을 보지 못했을 때, 발생하는 문제가 심각한 단계라면, 설계나 구현 자체를 수정하는 것이 좋아보인다.
- 6. TODO 주석 : 앞으로 할 일을 //TODO 주석으로 남기면 편하다. 다만, 나쁜 코드를 남겨두는 핑계가 되어서는 안된다.
PR을 남길 때, 기능 단위로 남기려고 하는 경향이 있었는데, 하나의 PR이 너무 커질 경우에 그 단위를 쪼개면 가끔 구현이 완료되지 않는 영역이 생긴다. 이럴 경우는 앞으로의 할 일을 주석으로 남기면 팀원 간의 소통이 되기도 한다. 다만, 너무 오랫동안 남기는 것은 좋지 않은 것 같다.
- 7. 중요성을 강조하는 주석 : 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용한다.
4. 나쁜 주석
대다수 주석이 나쁜 주석에 속한다
- 1. 주절거리는 주석 : 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비이다. 다른 코드를 뒤져봐야 이해할 수 있는 주석은 시간 낭비이다.
- 2. 같은 이야기를 중복하는 주석 : 코드보다 더 많은 정보를 제공하지 못하는 주석, 그저 코드의 내용을 중복해서 알려주는 주석의 경우 오히려 주석을 읽는데 더 시간을 오래걸리게 한다.
- 3. 오해할 여지가 있는 주석 : 때때로 의도는 좋았으나 오해할 여지가 있는 코드는 없으니만 못하다.
- 4. 의무적으로 다는 주석 : 의무적으로 주석을 달게 하면 오히려 코드를 헷갈리게 만들고, 잘못된 정보를 억지로 제공할 여지가 생긴다.
- 5. 이력을 기록하는 주석 : 모듈을 편집할 때마다 모듈 첫 머리에 주석을 추가하는 것은 구시대적 산물이다.
현재는 코드 관리 시스템(Git) 이 잘 되어 있기 때문에, 그럴 이유가 전혀 없다.
- 6. 있으나 마나 한 주석 : 쉽게 말해, 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.
- 7. 위치를 표시하는 주석 : 위치를 표시하기 위해 무의미한 주석을 다는 것은 좋지 않다. 특히 뒤에서 '/'를 반복하는 것은 좋지 않다.
Xcode에서는 MARK 표시를 통해서 위치 표시를 종종하곤 한다. 200~300 줄 넘어가는 코드의 경우 해당 표시를 통해서 빠르게 이동할 수 있어, 편리하다.
- 8. 닫는 괄호에 다는 주석 : 때로는 개발자들이 닫는 괄호에 특수한 주석을 달아놓는다. 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만 작고 캡슐화된 함수에는 잡음일 뿐이다. 그러므로 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도해야 된다.
- 9. 주석으로 처리하는 코드 : 주석으로 처리하는 코드만큼 밉살스러운 관행도 드물다. 코드를 주석처리 해두면 왜 이렇게 뒀는지 이유를 알 수 없기에, "무슨 이유가 있겠지?" 라고 생각할 것이다.
- 10. HTML 코드 : 저자가 생각하는 가장 혐오스러운 주석이라고 할 만큼 안 좋은 주석이다.
- 11. 전역 정보 : 주석을 달아야 한다면 근처에 있는 코드만 기술해야 된다. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 말아야 한다.
주석은 바로 위 아래의 코드에 대한 설명만 기술하는 것이 좋은 것 같다.. 오픈 소스를 볼 때, 주석을 보면 위 아래로 그 내용을 본능적으로 찾았던 것 같다. 만약 전역 정보로 기술 할 것이 있다면, 맨 위에 기술을 한다던지 혹은 README, 공식문서를 만드는 것이 좋을 것 같습니다.
- 12. 너무 많은 정보 : 주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓으면 안됩니다.
- 13. 모호한 관계 : 주석 자체가 다시 설명을 요구하는 것은 주석을 잘못 단 것입니다. 주석의 목적은 코드를 보충하는 것이지 그 보충 설명이 추가 설명을 필요로 하면 안됩니다.
e.g. 정수 등의 숫자에 대한 설명 없이 그 숫자의 의미를 알고 있는 작성자가 의미만 주석으로 달아 놓는다면, 이 주석을 읽는 다른 사람은 그 숫자와 의미가 매칭 되지 않아 주석을 이해하지 못할 수 있습니다.