[번역]주석에대하여

제목: On Comments

원문: http://khanlou.com/2017/03/on-comments

코드를 작성할때 가장 큰 적은 복잡성이다. 추상화 수준(level of abstraction)을 유지하고, 코드베이스에서 작업하는 개발자들은 그 개념으로 동작하게 하는 것은 큰 소프트웨어 프로젝트에서 필수적이다.

주석는 복잡성을 유지보수하는 도구이기도하지만, 때로는 돕는게 아니라 미묘하게 코드베이스를 상하게 만들기도 한다.

주석의 내 견해는 두가지로부터 온다. 1) 주석은 컴파일하지 않는다. 2) 주석은 연하게 문법 하이라이트된다. 이것은 컴파일 되지 않고 시아에서 흐릿하게 보이기 때문에 코드에 변경사항이 생길때 무시되기 쉽다. 코드는 변경했는데 주석은 바뀌지 않는다면, 코드의 내용을 정확하게 반영하지 않은 주석과 함께해야한다.

이상적인 세상에서는 코드 리뷰때 이것을 발견할 수도 있지만, 실제로는 절때 발견하지 못할때도 있다. 코드 리뷰 툴이 문법 하이라이트 기능을 가지고 있더라도 주석은 그 문맥에서 백그라운드로 사라지게된다. 또한, 코드 리뷰는 변경된 부분의 주변만 보여주기 때문에, 오래된 주석은 그 자체가 변경될 쯤에만 발견될 수 있을 것이다. 만약 메소드의 전제조건을 변경하여 한 라인을 바꿨다면, 리뷰어는 주석을 보지 못한채로 바꿔라고 말하지 못할 것이다.

일반적인 주석을 피하는 몇가지 방법이 있다. 그 중 몇개는 a blog post by an old manager of mine에서 다루고, 나머지는 Andrew에서 나온 것인데, 루비에서 나온 것이므로 다이나믹 타입 언어에대한 이야기여서, 적용시킬 수 없다.

1. 이름을 잘 정하자! 주석을 피하는 첫번째 방법은 다음과 같다. 한 단어 이름, 추상적인 이름, 모호한 이름을 피하자. 여러분이 할 수 있는 만큼 더 정확하게 이름을 정할수록 주석을 달 필요가 줄어든다.
2. 메소드에 전제조건이 있으면 유효하지 않은 값이 들어올때 앱이 크래쉬내는 assertion를 넣자(항상 그러지는 말고 디버깅때만!). 만약 양수지만 0이아닌 정수만 받는다면 코드에 precondition(int>0)으로 작성할 수 있다.
3. 런타인 assertion보다 나은 것이 컴파일타임의 것이다. 만약 메소드가 비어있지 않는 배열만 받는다면 precondition(!array.isEmpty)를 쓸 수 있다. 그러나 절때 빈 배열이 되지 않는 타입을 사용하는 것도 하나의 방법이다. 여러분의 API의 사용자들은 이제 절때 파라미터에 빈 배열을 보낼 수 없을 것이다.같은 성질에서, 두 이름을 case를 가진 열거형으로 표현된 것보다 더 잘 표현된 불(bool) 파리미터를 가져본 적이 있는가? 다른 열거형처럼 여러분의 옵셔널이 더 잘 표현되는가?  여러분의 의도를 네이밍에 드러내라.
4. 임시 코드, 프로토타입 코드에 표시를 하자. 나는 종종 이 함수가 이상적으로 짜지지 않았으면 hack_를 표시한다. 스위프트에서 메소드의 언더바는 내 코드베이스를 좋지않게 만들어 괴롭히므로 보기에 거슬린다.그리고 이것을 상기시켜 고치게 만든다. 우리는 최근에 shouldReallyBeInTheCoordinator_를 접두에 붙인 함수를 만들었는데, 코드리뷰를 받아야야할때 코드가 올바른 클래스에 있지 않았기 때문이다. 올바르지 않은 코드가 거슬리게 생긴다면, 코드베이스 요구와 여러분의 감정이 드러맞게 된다. 또다른 좋은 접두에는 perf_나 temp_ 같은 것들이 있다.
5. Mark Sands에 의하면, ID를 버그 추적기에서 메소드 이름으로 인코드 할 수 있고, 이것은 스택 트레이스(stack traces)에서 나타날 것이다. UIKit은 몇 케이스에서 레이더 넘버(Radar Number)를 참조한다. 이것은 현실이다.

   -[UIViewController _hackFor11408026_beginAppearanceTransition:animated:]

6. 함수의 이름이 "왜" 이것인지 설명하는 것을 두려워하지마라. updateFrameOnNextTickBecauseAutoLayoutHasntCompletedYet(frame: CGRect)처럼 함수를 만들 수 있다. 컴파일러는 메소드 길이를 신경쓰지 않으며 코드는 작성하는 수보다 읽히는 횟수가 더 많다. 주석은 단지 단어들이며 메소드 이름이다. 그 코드베이스의 미래 유지보수 담당자는 여러분의 장황한 설명에 감사할 것이다.
7. TODO(date: Date, message: String) 같은 보조함수(helper function)을 만들어라. 여기서 TODO는 어떤 날짜를 정하지 않으면 에러를 출력한다. (혹은 디버깅에서 크래쉬를 내는게 더 나을 수도 있다) Jordan Rose의 또다른 예제이다.
8. 테스트에 어떤 알고리즘 요구사항을 인코드하라. 만약 위의 모든것이 실패하고, 특정 문제를 풀기에 precondition, 타입, 메소드이름에 의존할 수 없다면, 테스트를 작성하라. 이것은 특히 엣지 케이스에 좋다. 누군가 코드를 다시 작성했는데, 테스트에 실패한다면 새로운 코드안에 다뤄줘야할 케스이가 있다는 사실을 알게될 것이다.

기억하기: 받아드리기 힘든 코드를 작성하거나 주석이 없는 코드는 변명할 수 없다! 주석을 스킵한 코드는 반드시 명확해야한다. 결국에는 나를 위한 주석이다. 다음 프로그래머에게 내 의도를 표현할 수 있는 또다른 방법을 찾을 수 있다면 주석을 달지 않을 것이다.

더 읽을거리

• Erica Sadun’s counterpoint on why comments are actually good

---

이 블로그는 공부하고 공유하는 목적으로 운영되고 있습니다. 번역글에대한 피드백은 언제나 환영이며, 좋은글 추천도 함께 받고 있습니다. 피드백은 

• 블로그 댓글 
• 페이스북 페이지(@나는한다번역) 
• 이메일(canapio.developer@gmail.com) 
• 트위터(@canapio) 

으로 보내주시면 됩니다.