[Clean code] chapter 4. 주석

Overview

우리는 가끔씩 코드를 작성하다가 코드를 설명하기 위해서 주석을 작성한다. 어떻게 하면 주석을 잘 적성할 수 있을까? 한번 알아봅시다!! 어떤 프로그램이든 가장 기본적인 단위가 함수다. 이 장은 함수를 잘 만드는 법을 소개한다.

규칙

들어가기 전에

잘 달린 주석은 그 어떤 정보보다 유용하다. 그런데 오히려 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.

주석은 순수하게 선하지 못하다. 사실상 주석은 기껏해야 필요악(없는 쪽이 바람직하지만 조직 등의 운영상(運營上) 또는 사회 생활상 어쩔 수 없이 필요한 일. 정의 출처: Oxford Languages)이다. 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 전혀 필요하지 않다.

우리는 코드로 의도를 표현하지 못해, 한마디로 실패하여서 사용하는 것이 주석이다. 그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다.

왜 주석은 별로인가?

이렇게 주식을 무시하는 이유는 바로 거짓말을 자주, 아니 매번하기 때문이다. 코드는 계속 변화한다. 그리고 진화한다. 하지만 개발자들은 그 코드와 관련된 주석을 따라가지 못한다. 그러기 때문에 잘못된 정보를 주고 개발자들에게 좋지 않은 정보를 준다.

그리고 주석은 우리가 만든 나쁜 코드를 보완해주지 못한다. 실제 코드 퀄리티는 똑같고 실제로 나쁘기 떄문에 주석을 다는 것이니 주석말고 코드로 그 부분을 해결하려고 노력하는 것이 맞다.

잘못된 주석은 주석이 없는 것보다 더 바쁘다. 그러기 때문에 주석은 정말 불가피한 상황에서만 사용해야만 한다.

간단한 예를 보여주겠다.

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flash & HOURLY_FLAG) && emplyee.age > 65)
---
if(employy.isEligibleForFullBenefits())

그대는 위 두개의 코드를 보고 어떤 것이 더 좋아보이는가? 당연히 저렇게 만드는 것에 대한 노력은 필요하다. 하지만 저 주석을 쓸 시간과 나중에 내가 혹은 이 코드를 수정할 사람들의 시간을 모두 생각한다면 조금 더 고려하여서 만들어보자!

좋은 주석

어떤 주석은 필요하고 유익하다. 그런 주석들을 소개하겠다.

법적인 주석

소스 코드 저작권 정보와 소유권 정보는 필요하다고도 타당하다. 그런 부분을 코드 처음에 주석으로 추가하는 경우가 있다. 혹은 라이센스 같은 경우를 추가한다. 이런 것들은 반드시 필요한 경우가 있기 때문에 주석을 사용해도 좋다.

정보를 제공해주는 주석

때로는 기본적인 정보를 주석으로 제공하면 편리하다. 예를 들자면

// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();
---
protected abstract Responder responderBeingTested();

당연히 밑에 있는 이름을 사용하면 주석을 지울수도 있겠지만 이렇게 명확하게 어떤 것인지 설명하는 주석은 좋다.

의도를 설명하는 주석

어떤 코드를 만들었을 때 그 코드가 어떤 의도로 만들어지고 동작하게 했는지 적는 것은 소스 코드를 이해하는데 엄청난 도움을 준다. 당연히 코드로 그런 내용을 설명하면 좋겠지만 그러지 못하는 경우가 많았기 때문에 그런 경우 사용해서 설명해보자

TODO 주석

때로는 //TODO 주석~~~~ 주석으로 남겨두면 편하다. 다음은 함수를 구현하지 않은 이유와 미래 모습을 주석으로 설명할 수 있다.

당장 구현을 하지 않더라도 나중에 필요한다던지 프로토타입을 만들기 위해서 사용하기도 하니 좋은 주석이라고 생각한다. 하지만 단순히 미래만 생각하고 구현하지 않는 경우도 있는데 시간 날때마다 IDE에서 TODO 주석을 바로 찾을 수 있으니 시간 날때마다 구현해서 없애는 게 좋다!

중요성을 강조하는 주석

특정 로직에서 굉장히 중요한 부분은 존재한다. 로직에서 해당 부분이 왜 들어가는지 이런 것들이 존재하는데 그것을 설명하는 주석이다. 혹은 해당 코드가 왜 들어가 있는지 설명하기 때문에 수정에 있어서 굉장히 신중하게 될 것이다.

나쁜 주석

방금 위에 말한 경우를 제외한 경우는 모두 이 범주에 속한다. 대다수 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변경하는 듯 나를 포함 다른 사람에게도 도움이 되지 않는 주석들이다! 꼭 피하자!!

주절거리는 주석

주석을 작성하는데 의무감에 도움을 주는 주석이 아닌 정확한 정보를 주지 않는 주석이다. 한마디로 정확하게 설명하지 못하는 주석이어서 오히려 주석이 코드 해석에 악영향을 줄 수 있다.

같은 이야기를 중복하는 주석

주석이 메소드 이름이나 간단하게 로직만 보면 알 수 있는 내용을 중복해서 말하는 경우가 있다. 이런 경우 심지어 간단하게 말을 하려다가 정보를 잘 못 전달하는 경우가 있는데 이런 경우 더 악영향을 준다.

그 뿐만 아니라 라인 하나하나 주석을 다는 경우도 있는데 이런 것들은 충분히 네이밍으로 설명이 가능한 경우도 주석을 달게 되면 오히려 주석을 읽고 싶지 않게 만드는 주범이 된다.

의무적으로 다는 주석

모든 코드에 주석을 달아야된다고 생각하여 작성하는 주석은 전혀 필요하지 않다. 당연히 알고 있는 내용에 다는 주석은 주석을 읽도록 만들지 못하며 심지어 그런 주석들은 나중에 수정이 없어서 필요없어지는 경우가 더 많다.

이력을 기록하는 주석

이전에는 이력을 기록하는 것은 의미가 있었다. 하지만 이젠 버전 관리 시스템이 있어서 그런거 필요없다. 어차피 다 알 수 있다. 그냥 쓰지 말아라!

닫는 괄호에 다는 주석

엄청나게 중첩된 코드인 경우 해당 블럭이 언제 끝나는 지 알기 위해서 작성하는 경우가 있다. 이런 경우 차라리 그 블럭을 메소드로 만들어서 블럭을 최대한 줄이는 방식으로 활용하는 게 좋다.

주석으로 처리한 코드

이런 경우는 보통 관행이라는 생각으로 지우지 않는 경우가 있다. 하지만 이런 코드는 결국 별로 필요가 없다. 이렇게 주석을 남는 이유가 무엇일까? 급해서? 어떤 이유에서든 남겨둘 이유가 없다. 어차피 버전관리시스템에 다 저장되는데 왜 이렇게 남기는 것이냐?

전역 정보

전역 변수에 대한 정보를 특정 메소드나 로직에 가져와서 변수를 설명하는 주석을 넣을 수 있다. 하지만 이런 경우 전역 변수가 수정에 대해서 이런 주석이 수정될 일이 매우매우 적다. 그러기 때문에 오히려 잘못된 정보를 줄 수 있다.

마무리

사실 내가 실제로 이렇게 주석을 작성한 적도 있다. 학교 수업에서는 과제에서 강제로 모든 라인에 주석을 달라고 한다. 그런 생각에 주석을 무조건 살아야되나? 이런 생각을 한적도 있고 의무적으로 주석을 단 적도 있다. 하지만 이런 글을 보니 오히려 주석이 독이 될 수도 있다는 생각을 하게 되었다.

현재도 개발을 하면서 주석보다는 코드를 더 많이 보게 된다. 그런데 가끔 주석을 봤을 때 어느정도 맹목적으로 믿는 경우가 있었는데 이런 경우을 항상 주의해야 겠다는 생각을 했다.

주석보다는 코드이지만 어쩔때는 주석이 필요한 경우가 있다. 이런 경우를 한번 잘 생각해보고 주기적으로 좋은 주석을 달기 위해 노력해봐야 겠다.