#클린코드 - 주석 (2)

이번엔 주석을 어떻게 명확하고 간결하게 다는지 살펴볼 것이다.

 

좋은 주석은 짧은 문장에 많은 정보를 가져야 한다.

 

1. 주석을 간결하게 하라

1줄으로 설명 가능한 것을 3줄으로 길게 쓰면서 허비하지 마라.

 

2. 모호한 대명사를 피하라

'위의', '아래의', '지난 버전' 등등의 대명사는 보는 사람마다 다른 의미를 떠올릴 수 있고, 정확한 해석을 하기 위해서는 추가적인 노력이 필요하다. 주석내에서 대명사를 쓸때는 대명사의 의미가 명확하게 표시될 수 있는 문장에서 사용하거나, '위 saveMyName() 함수에서' 와 같이 명확한 대상을 가르켜야 한다.

 

3. 문장을 다듬어라

'이 URL을 전에 방문했는지에 따라서 다른 우선순위를 부여한다.'

이 문장은 해석 가능하지만 아래 문장을 살펴보자.

'전에 방문하지 않은 URL에 높은 우선순위를 부여하라.'

두 가지를 비교해보면 아래의 문장이 간단하고 짧고 명확하다.

 

 4. 코드의 의도를 명시하라

대다수의 사람들은 아래와 같이 주석을 단지 코드가 수행하는 동작을 문자 그대로 설명하는 데 그친다.

'리스트를 역순으로 반복한다.'

위와 같은 주석 보다는 아래와 같이

'각 가격을 높은 값에서 낮은 값 순으로 나타낸다.'

위 와 같이 더욱 많은 정보를 가진 주석으로 나타낼 수 있다. 또한, 첫번째 주석인 경우 가격이 이미 정렬이 되어있을때는 원하는 동작과 반대로 동작하게 되어 버그가  발생한다. 이러한 관점에서도 두번째 동작이 오류를 파악하기 쉽다.

 

5. 의미를 함축하는 단어로 문장을 구성하여 주석을 간단하게 만들어라.

'값을 메모리에 저장하고 후에 사용할 수 있도록 한다.'

위 문장은

'값을 캐싱한다'

와 같이 축약형 단어를 사용하여 표현할 수 있다.