4. 주석

나쁜 코드에 주석을 달지 마라. 새로 짜라

주석은 나쁜 코드를 보완하지 못한다.

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

주석을 달기보단, 그 코드를 깔끔하게 개선하는데에 시간을 투자해라.

코드로 의도를 표현하라!

if(employee.isEligibleForFullBenenfits() 같이 주석을 대신해 함수로 충분히 표현이 가능하다.

좋은 주석

하지만 어떤 주석은 필요로 한다. 그 주석의 종류를 열거하자면,

1. 법적인 주석 - 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣는 경우
   

2. 정보를 제공하는 주석 - 기본적인 정보를 주석으로 제공하면 편리함.
   
   혹은 파라미터 등에서 어떤 포멧인지 (하지만, 필수는 아님. 함수명을 변경함으로 충분히 대체 가능)

3. 의도를 설명하는 주석 - 구현을 이해하게 도와주는 형태의 주석, 주로 저자의 구현 의도가 드러나는 주석이라 할 수 있다.

4. 의미를 명료하게 밝히는 주석 - 모호한 인수나 반환값을 읽기 좋게 표현하는 것

5. 결과를 경고하는 주석 - 특정 테스트 케이스에서 실행할 경우 문제가 생길 수 있다는 것을 설명해주는 것

6. TODO 주석 - 때로는 앞으로 할 일을 남겨놓을 필요가 있기 때문에 사용한다.
   
   하지만, 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안된다.

나쁜 주석

대다수의 주석이 이 범주 안에 속하며, 허술한 코드를 변명하는 것에 지나지 않는다.

1. 주절거리는 주석 - 의무감 혹은 프로세스에 의해서 주석을 다는 경우는 시간 낭비이다.
   
   주석을 달기로 했으면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.

2. 같은 이야기를 중복하는 주석 - 헤더에 달린 주석이 같은 코드 내용을 그대로 중복하면 자칫 코드를 읽는데 시간이 더 소요될 수 있다.

3. 오해할 여지가 있는 주석 - 분기 처리 등에서 설명이 살짝 부족한 경우 충분히 오해의 소지가 있어,
   
   관련 기능을 포함하여 테스트 혹은 개발을 할 때 문제가 생길 여지가 다분하다.

4. 의무적으로 다는 주석 - 무조건적으로 다는 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고 혼동을 줄 여지가 충분하다.

5. 있으나 마나 한 주석 - 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석 ex) // 생성자

함수나 변수로 표현할 수 있다면 주석을 달지 마라

닫는 괄호에 다는 주석

때로는 괄호가 닫히는 곳에 주석을 달곤 하는데 (주로 반복이 중첩되거나, 여러 분기가 있는 경우) ,

괄호에 주석을 달아야 겠다고 생각한다면, 그 에너지를 함수를 줄이는 것에 사용하자.

저자를 표시하는 주석

근래의 소스 코드 관리 시스템은 누가 언제 무엇을 추가했는지 귀신처럼 기억한다.

그러므로 굳이 주석을 달아서 코드를 오염시킬 필요가 없다.

주석으로 처리한 코드

주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 우리는 우수한 소스 관리 시스템을 사용하기 때문에,

굳이 주석으로 남길 필요가 없다. 그냥 코드를 삭제해라, 코드를 잃어버릴 염려는 없다.

전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술하라. 전역적인 정보를 기술하지 마라.

만약 전역정보가 변한다고 해도, 그 주석에 있는 전역 정보에 대한 서술이 바뀔 가능성은 낮다.

모호한 관계

주석을 달았다면 적어도 독자가 주석과 코드를 읽어보고 무슨 소린지 알아야 한다.

주석 자체가 다시 설명을 요구한다면, 그것은 잘못된 주석이다.

덧붙이면...?

나는 변수와 메소드 명을 중요시 하게 여긴다.

개발자라면, 코드로 의도를 전달할 수 있어야 한다고 생각하기에 주석은 가급적 피하는 편이다.

그리고 이번 장은 그런 나의 의도와 잘 맞는 장이라고 할 수 있겠다.

책에서도 나오는 얘기지만, 예전에는 해당 함수 등의 내용이 변경되면 기존 코드를 주석으로 해놓고, 새 기능을 작성했다.

아까워서 그랬는지, 나중에 쓸까봐 그랬는지는 지금와서는 잘 기억이 안 나지만(아마 후자가 아닐까 한다.)

이제는 미련없이 지운다. 경험상 그 주석 처리한 코드를 쓴 일은 없었고(짧은 경험이긴 하지만....), 설사 쓴다해도 되돌리면 그만이다.

그리고 혼자 개발하다보니 당장 좋은 방법이 생각 안나거나 할 때 TODO,FIXME 등을 꽤 애용하는 편인데(미래의 나야 부탁해)

책에서도 언급했듯이 TODO 떡칠을 항상 경계해야 할 것 같다.