"주석이 필요한 코드는 나쁜 코드이다" 라는 격언을 처음 코딩을 시작하면서 들어왔다. 동의하는 바이다. 많은 사람들이 사용하는 오픈 소스 라이브러리만 봐도 주석이 많이 들어가는데, 주석이 있기 때문에 코드가 잘 읽히는 경우는 거의 없다. 코드를 이해한 상태에서 주석을 보면 부가적인 정보들을 얻는 경우가 대부분이였다. 이렇게 적당히 잘 사용하면, 코드의 질 자체도 높은 상태에서 부가적인 정보도 줄 수 있어 주석이 참 요긴하게 사용된다.
평소에 주석을 잘 사용하지 않는데, 며칠 전 SDK를 만드는 과제 전형을 진행하면서 주석을 넣을까 말까... 어떻게 써야할까 에 대해서 고민을 많이 했던 것 같다. 물론 넣지 않았지만..ㅎㅎ 오늘은 어떻게 하면 코드의 질을 높이는 주석을 쓸 수 있을지 알아보도록 하겠다.
코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 힘드니, 그것을 보완하기 위해서 주석을 단다. 하지만, 코드를 처음 보는 사람 입장에서는 코드가 엉망이면 주석이 전혀 도움이 되지 못한다.
확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다. 하지만, 이는 코드가 훌륭한 수단이 아니라는 의미는 아니다.
if ((employee.flags & HourlyFalg) && (employee.age > 65))
if (employee.isEligibleForFullBenefits())
두 표현의 차이를 보면, 밑에 if문이 의도를 파악하기 쉽다는 것을 알 수 있을 것이다
주석이 필요하며, 유익한 경우가 존재한다.
때때로 구현을 이해하는데 편하게, 구현 의도를 설명해야 되는 때가 있다. 그럴 경우는 보통은 PR을 통해서 코드 리뷰때 설명하면 되기에 굳이 주석으로 남겨야되나 싶다. PR도 기록된 문서로 볼 수 있기 때문이다.
이 부분은 앞에 "코드로 의도를 표현하라" 의 내용처럼 코드로 표현해야 된다고 생각한다. Swift API GuildLines 에서도 언급하는데, 전달인자를 통해서 모호한 인수를 더 이해하기 좋게 표현하라고 언급하고 있다.
e.g. // 여유 시간이 충분하지 않다면 실행하지 마십시오. -> JUnit의 경우 @Ignore로 끌 수 있어요.
// 객체가 Thread Safe하지 못하므로 인스턴스를 독립적으로 생성해야 한다.
물론 Xcode 에서 테스트 케이스의 경우 각 테스트 메서드마다 테스트가 수행되기 때문에 이렇게 할 필요는 없지만, 결과를 경고해야 되는 이유가 있다면 해당 경우는 주석을 남기는 것이 나빠보이지는 않는다. 허나, 주석을 보지 못했을 때, 발생하는 문제가 심각한 단계라면, 설계나 구현 자체를 수정하는 것이 좋아보인다.
PR을 남길 때, 기능 단위로 남기려고 하는 경향이 있었는데, 하나의 PR이 너무 커질 경우에 그 단위를 쪼개면 가끔 구현이 완료되지 않는 영역이 생긴다. 이럴 경우는 앞으로의 할 일을 주석으로 남기면 팀원 간의 소통이 되기도 한다. 다만, 너무 오랫동안 남기는 것은 좋지 않은 것 같다.
대다수 주석이 나쁜 주석에 속한다
현재는 코드 관리 시스템(Git) 이 잘 되어 있기 때문에, 그럴 이유가 전혀 없다.
Xcode에서는 MARK 표시를 통해서 위치 표시를 종종하곤 한다. 200~300 줄 넘어가는 코드의 경우 해당 표시를 통해서 빠르게 이동할 수 있어, 편리하다.
주석은 바로 위 아래의 코드에 대한 설명만 기술하는 것이 좋은 것 같다.. 오픈 소스를 볼 때, 주석을 보면 위 아래로 그 내용을 본능적으로 찾았던 것 같다. 만약 전역 정보로 기술 할 것이 있다면, 맨 위에 기술을 한다던지 혹은 README, 공식문서를 만드는 것이 좋을 것 같습니다.