#클린코드 - 주석 (1)

 주석

주석의 목적은 무엇인가?

대부분의 프로그래머가 생각하는 주석의 목적이 무엇일까?

‘단순히 아래 나와 있는 코드에 대한 설명’

‘나중에 설명하기 귀찮으니 써놓는 것’

‘나쁜 코드를 가리기 위한 변명’

등등 저는 여러가지 이유로 코드에 주석을 쓰고 있다.

최근 클린 코드에 관한 책을 읽으며

 

’주석의 목적은 코드를 읽는 사람이 코드를 작성한 사람만큼 코드를 잘 이해하게 돕는데 있다‘

 

라는 문구를 보았다.

이러한 개념에 대해서는 당연히 알고 있었지만 어떻게 해야 좋은 주석을 작성하고 사람들을 이해시킬 수 있을지에 대한 생각은 깊게 해보지 않았다.

오늘은 어떤 주석이 좋은 주석이며 어떤 주석을 작성하지 말아야 할지 알아보는 시간을 가져보도록 하겠다.

 

설명하지 말아야 하는 것

//유저 Id를 가져오는 함수

const getUserId(){}

 

//저장 버튼을 클릭 했을때 실행 되는 함수

const onClickSaveButton(){}

 

위 주석은 모두 가치가 없다.

이러한 주석은 새로운 정보를 제공하지도 않고 주석이 없어도 유추할 수 있는 내용이기 때문에 가치가 없는 주석이다.

 

코드에서 빠르게 유추할 수 있는 내용은 주석으로 달지 말라.

 

// 두 번째 ‘*’ 뒤에 오는 내용을 모두 제거한다

name = ‘*’ .join(line.split(‘*’)[:2])

 

위 주석에서는 새로운 정보가 없다 코드를 보고 유추할 수 있기 때문이다. 하지만 대부분의 프로그래머는 코드가 아닌 주석을 읽고 정보를 빠르게 파악한다. 이 처럼 빠르게 라는 형용사도 주석에서 매우 중요한 역할을 한다.

 

설명 자체를 위한 설명을 말라

주석을 달아야한다는 의무감 때문에 굳이 설명하지 않아도 될 것을 설명하지 마라.

 

//트리의 특정 노드를 이진검색 알고리즘으로 검색한다

const findNodeByBinarySearch(){}

 

위 주석은 함수의 선언과 주석의 내용이 일치하므로 무가치한 주석에 해당한다.

꼭 주석을 써야한다면 더 중요한 세부 사항을 적어 내부 구현을 유추할 수 있게 하면 좋을 것이다.

 

나쁜 이름에 주석을 달지 마라

나쁘게 지은 변수, 함수에 대한 주석을 달 이유는 없다.

주석을 달아야 할 만큼 잘못 지은 이름은 함수를 스스로 설명할 수있게 이름을 다시 짓는것을 고려해 보아라.

 

생각을 기록하라

이제 주석으로 무엇을 설명해야 하는지 알아보자.

 

‘감독의 설명’을 포함하라

영화에는 종종 영화 제작자들이 자신의 통찰을 설명하고, 영화가 만들어진 과정을 관람객이 잘 이해하게 도와주는 ‘감독의 설명’을 담은 트랙이 있다. 이와 비슷한 방식으로 중요한 통찰을 코드에 포함시켜야 한다.

 

예를 들면

 

// 아래 함수는 우리 데이터에서는 이진트리가 해시테이블보다 빠르다.

 

// 여기서 몇가지 생략되는 단어가 있지만 100% 해결은 쉽지 않다. 버그가 아니니 이대로 동작하게 두자.

 

// 이 클래스는 엉망이다. 분리를 해야할 것 같다.

 

와 같이 코드가 왜 이렇게 쓰였고 어떤 조치를 취해야하는지를 적어 놓으면 다른 사람이 보았을때 최적화를 하느라 시간을 허비하지 않고, 버그가 있다고 생각하여 고치는데 시간을 허비지 않을 것이다.

 

코드에 있는 결함을 설명하라

코드는 지속적으로 개선이 필요하다. 코드가 불완전할 때 혹은 다른사람의 코드에 개선사항이 있을때 주석을 남겨 추후 개발시에 참고가 될 수있다.

 

상수에 대한 설명

상수를 정의할 때는 종종 그 상수가 무엇을 하는지, 왜 이러한 값을 갖게 되었는지 ‘사연’이 존재하기 마련이다.

 

NUM_THREADS = 8 # 이 상수값이 2 * num_processors보다 크면 안된다.

 

위와 같이 상수값의 가이드를 적어주어 왜 이런 값을 가지게 되었고 어떤 값이 들어가면 안되는지를 설명해주면 코드를 보는사람이 상수의 역할을 더 명확히 알 수 있게 된다.