주석(comment)의 중요성은 수도 없이 들어왔었다. 주석의 남발을 조심해라, 남들이 볼 때 무슨 일들을 하는지 알 수 있는 주석을 달아라 등 수 많은 주석과 관련된 조언들이 인터넷과 현실에서 돌아다니고 있다. 그만큼 명확하고 좋은 주석이 얼마나 코드 해석에 도움이 되는지를 이야기 하는 것이라고 생각이 된다.
나도 코딩을 약 5년여간 해오면서 늘 고민인 두 가지 중에 하나가 주석이었다. (또 다른 하나는 변수와 함수의 이름 짓기이다.) 클린 코드라는 책을 비교적 일찍 접했기 때문에 늘 고민해오던 주제였기에 오늘 정리를 해보면서 나의 주석 습관을 다시 돌아보려고 한다.
이 책에서는 주석 없이 해석될 수 있는 코드를 가장 좋은(깨끗한) 코드라고 하고있다. 하지만 모든 코드가 완벽하게 무결할 수는 없기 때문에 어떻게 하면 좋은 주석을 달 수 있는지에 대해서 소개하고 있다.
주석은 나쁜 코드를 보완하지 못한다
코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
일반적으로 코드만으로는 이해하기 어렵기 때문에 주석을 추가하게된다. 결국엔 주석을 달 필요가 거의 없는 코드가 주석이 주렁주렁 달린 코드보다 좋다.
코드로 의도를 표현하라
코드만으로 대다수의 의도를 충분히 표현할 수 있다. 함수명만으로도 주석으로 달 설명을 충분히 대체할 수 있다.
좋은 주석
책에서 몇 가지 좋은 주석의 경우를 소개하고있다. 당연히 주석 없이 표현되는 코드가 제일 좋다는 의견은 여지없이 그대로이다.
법적인 주석
회사 등에서 법적인 이유로 인해 특정 주석을 넣어야하는 경우가 있다. 이런 경우 소스 파일 첫 머리에 들어가는 저작권 정보와 소유권 정보는 필요하며 주석을 넣을 이유가 타당하다.
정보를 제공하는 주석
정보를 제공하는 주석은 당연히 유용하다. 그러나 주석대신 함수 이름 등에 정보를 담아서 알 수 있도록 하는 것이 더 좋다. 그럼 어떤 정보를 제공해야 좋은 주석일까?
대표적으로 정규표현식같이 한 눈에 들어오기 어려운 정보에 대해서 정보를 제공하는 경우 주석을 다는 것은 정보 제공 측면에서 좋은 주석이라고 할 수 있다. 이 책에서는 이 부분을 또 다른 클래스나, 함수로 만들어 옮기고 함수명 등으로 표현하는 것이 더욱 좋은 방식이라고 한다.
의도를 설명하는 주석
때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.
의미를 명료하게 밝히는 주석
모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다. 물론 인수나 반환값이 명료하면 좋겠지만 그러지 못한 경우엔 그 의미를 명료하게 알 수 있는 주석을 달면 좋다.
결과를 경고하는 주석
다른 프로그래머에게 결과를 경고하기 위한 목적으로도 주석을 사용한다.
TODO 주석
앞으로 할 일에 대해서 TODO 주석을 달아두면 편하다. ide의 발달로 TODO 주석을 찾기 쉬워졌으므로 부담없이 남기고, 해결된 문제에 대해서는 지우도록 한다.
중요성을 강조하는 주석
대수롭지않게 넘길 수 있는 대목에 대해 중요성을 강조하는 주석을 사용할 수도 있다.
공개 API에서의 Javadocs
API에 대한 설명을 적어놓은 Javadocs는 아주 유용하다. 대부분 훌륭한 문서지만, 그릇된 정보를 제공하고 있을 수도 있음을 유의하자
💬 자바스크립트에서는 JSDoc이라는 문서 양식이 있습니다.
나쁜 주석
좋은 주석들에 이어서 나쁜 주석들도 소개하고있다. 나쁜 주석들은 허술한 코드를 지탱하거나, 엉성한 코드에 대한 변명, 미숙한 결정을 합리화하는 것과 같은 프로그래머의 불필요한 독백이다.
주절대는 주석
특별한 이유없이 의무감/프로세스로 마지못해 적은 주석은 시간 낭비이다. 이런 주석은 작성자 외에게는 의미가 제대로 전달되지 않아서 다른 코드를 뒤져보는 등의 시간 낭비를 불러일으킨다.
같은 이야기를 중복하는 주석
코드에서 정보를 다 알 수 있는 경우, 코드를 설명하는 주석을 달면 코드를 읽는 시간이 길어지기만 한다. 이런 주석들은 종종 코드보다 부정확한 설명을 하는 경우가 있어서 독자에게 혼란을 초래할 수도 있다.
오해할 여지가 있는 주석
주석을 단 의도는 좋았으나 프로그래머의 의도에 딱 맞을 정도로 엄밀하게 주석을 달지 못하는 경우가 있다. 이런 경우에 '잘못된 정보'가 전달되어 본 의도와는 다르게 함수 등이 잘못 사용될 수 있다.
의무적으로 다는 주석
모든 함수에 대해서 주석을 다는 것 또한 어리석은 생각이다. 오히려 코드를 복잡하게 만들고 혼란을 초래할 수도 있다.
있으나 마나 한 주석
있으나 마나 한 주석이란, 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석을 의미한다.
무서운 잡음
Javadocs에 작성된 정보도 때론 불필요할 때가 있다. 정보를 제공해야한다는 의무감에 사로잡혀서 작성한 불필요한 docs는 아무런 정보도 이익도 제공하지 않는다.
함수나 변수로 표현할 수 있다면 주석을 달지마라
주석이 필요하지 않도록 코드를 작성하는 것이 더 좋다.
위치를 표시하는 주석
때때로 특정위치를 표시하기 위해 주석을 다는 경우가 있는데, 너무 남발하면 가독성을 낮춘다.
닫는 괄호에 다는 주석
닫는 괄호에 주석을 다는 프로그래머도 있다. 블록이 장황하고 중첩이 심하다면 유효할지도 모르겠지만 간단한 블록 끝에 주석을 다는 것은 별다른 도움이 안되는 잡음이다.
공로를 돌리거나 저자를 표시하는 주석
저자 정보 등을 소스 코드 관리 시스템에 등록하는 것이 좋다. 이런 주석들이 오랫동안 코드에 남아있으면 점점 부정확하고 쓸모없는 주석이 된다.
주석으로 처리한 코드
주석으로 지워둔 코드는 함부로 지우면 안된다고 생각하게 된다. 그리고 이런 주석들이 하나둘 모이면 쓸모없는 코드가 점점 쌓이게 된다.
예전에는 코드 변경을 기록하기 위해 주석 처리를 해두었다. 그러나 현재는 Git과 같은 소스 코드 관리 시스템들이 버전을 기록하고 관리해주기에 더 이상 주석으로 코드를 지워둘 필요가 없어졌다.
HTML 주석
HTML 형식의 주석은 사람이 읽을 때도, ide 등의 도구가 읽을 때도 힘들어한다.
전역 정보
주석을 달 때는 근처에 있는 코드만을 기술해야한다. 코드의 일부분에 시스템에 대한 전반적인 정보 주석을 달지 말아야한다.
모호한 관계
주석과 주석이 설명하는 코드는 둘 사이의 관계가 명확해야한다. 모호한 관계를 가진 주석은 그에 대해 또 다른 설명을 필요로하게 된다.
함수 헤더
짧은 함수에는 주석이 필요없다. 짧고 명료하며 이름이 명확한 함수는 주석을 헤더로 추가한 함수보다 좋다.
비공개 코드의 Javadocs
공개 API에서의 Javadocs는 유용하지만, 비공개 API의 Javadocs는 불필요하다. 유용하지도 않고 코드가 산만해진다.
후기
한 문장으로 정리할 수 있다.
나쁜 주석 === 내가 쓴 주석
주석을 심사숙고하며 다는 노력도 추가해야겠다. 특히 의무감에 작성하는 설명 주석을 많이 썼었는데 이 부분에 대한 점을 반성하며 좋은 주석을 다는 프로그래머가 되도록 노력해야겠다.
