이번 글에서는 A Philosophy of Software Design ( 이하, APoSD ) 이라는 책을 읽으면서 느꼈던 주석의 장점에 대한 이야기를 해보려고합니다.

주석의 단점

주석의 단점은 사실 거짓일 수도 있습니다.

보통 많은 책에서 주석을 쓰는 것에 대해서 부정적인 이야기를 많이합니다. 그렇게 말하는 사람들은 대부분 아래의 이유를 이야기합니다.

1. 코드 자체가 의미를 표현할 수 있어야 ( self-descriptive ) 한다
2. 주석은 최신화하기 어렵다
3. 잘못된 작성된 주석은 코드를 이해하는데 더 어려움을 겪게한다
4. 주석을 작성하는데 시간이 오래걸린다

물론, 이 네가지 이유는 코드를 작성하다보면 이해할 수 있는 의견이긴합니다. 하지만 APoSD에서는 이것을 정면으로 반박합니다.

1. 코드의 복잡도를 낮추기 위해 추상화를 하려면, 주석이 필수적입니다. 주석이 존재하지 않는다면, 메서드의 이름, 인수 그리고 반환 값을 보고 추론해야합니다.
2. 주석 수정이 코드의 수정보다 매우 쉽습니다. 주석을 한 곳에서 잘 관리하고, 코드 수정전에 주석부터 수정하는 습관을 들인다면 주석 수정은 매우 쉬운일로 변합니다.
3. 이것은 주석을 잘 작성하는 방식을 배우면 자연스럽게 해결됩니다.
4. 주석을 작성하는 시간은 사실 작업 시간의 10%도 들지 않습니다. 이 시간 정도는 투자해도 문제가 없습니다.

저자의 반박은 매우 합리적입니다. 하지만 저희는 아직 주석을 잘 작성하는 방법을 모릅니다.

이제부터 알아보겠습니다.

주석을 잘 작성하는 방법

주석은 코드에서 명백하게 드러내지 못하는 부분을 설명해야합니다.

주석을 잘 작성하기 위해서는, 주석은 코드에서 명백하지 않은 부분을 설명해야한다는 것을 명심해야합니다.

이제부터 코드에서 잘 드러내지 못하는 부분을 어떻게 주석으로 잘 작성할 수 있는지에 대해 알아보겠습니다.

주석의 종류

잘 작성하기 전, 주석의 종류부터 알아보겠습니다.

주석의 종류라니 익숙치 않은 개념이지만, 이 개념을 이해하고 어떠한 주석이 필요한지 이해해봅시다.

1. 인터페이스 주석 : 클래스, 자료구조, 함수, 메소드등의 인터페이스를 설명하는 주석. 메소드나 함수를 설명해야하는 경우, 그것의 전반적인 동작 방식과 인수 및 반환 값을 설명합니다. 만약 사이드 이펙트가 있다면, 그것도 명시해야합니다.

2. 자료 구조 주석 : 인스턴스 변수 혹은 정적 변수를 설명하기 위해 작성하는 주석

3. 구현 주석 : 메소드 혹은 함수 내부에 존재하는 주석으로, 코드가 내부에서 어떻게 작동하는지를 설명합니다.

4. 모듈 간 주석 ( Cross module comment ) : 모듈간의 관계를 설명하는 주석

주석이 위치해야 하는 곳

위에서 알아본 주석의 종류를 통해서, 코드의 어느 부분에 어느 주석이 정리해보겠습니다.

• 모든 클래스와 모든 인터페이스에는 인터페이스 주석이 있어야합니다.
• 모든 클래스 변수에는 자료구조 주석이 있어야합니다.

주석 작성시 주의점

지금까지 어떤 종류의 주석이 있고, 그 주석들은 어디에 위치해야하는지 알아보았습니다.

그럼 그 주석은 어떻게 작성하는게 좋을까요? 아래 내용들만 주의하면 됩니다.

• 코드를 반복해서 설명하지 않고, 다른 단어를 사용해서 설명하는 주석을 다는게 좋습니다.
• 코드에서 표현하지 못하는 수준의 주석을 작성해야합니다.
  • 코드보다 낮은 수준의 주석은 추상화를 제공할 수 있습니다. 이것이 주석의 가장 큰 역할이라고 할 수 있습니다.
  • 코드보다 높은 수준의 주석은 코드를 읽는이로 하여금 직관성을 높여줍니다.
• 구현 세부 사항과 관련된 주석은 주석을 어떻게 구현했느냐가 아닌, 무엇을 왜 구현했는지에 집중해서 적는게 좋습니다.

주석을 코드보다 먼저 작성해보기

주석을 나중에 해야 할 일이라고 미루지 마세요.

여태까지 주석을 잘 작성하는 방법에 대해 알아보았지만, 결국 제일 중요한 것은 주석을 작성하는 태도라고 생각합니다.

어떻게 해야 주석을 사용하는 것에 익숙해질 수 있을까요? 이 책에선 "주석을 코드보다 먼저 작성하는 방식"을 추천합니다.

보통 많은 사람들은 코드를 작성하고 나서 주석을 작성합니다. 하지만, 이 경우 미루다가 안쓰거나 적당히 타협하게 되는 일이 많아집니다.

이런 사람들에게 APoSD의 저자가 하고 싶은 말은 "주석을 코드보다 먼저 작성해라" 입니다. 주석을 먼저 작성하게되면, 주석을 잊어먹을 일도 없고 아래에서 설명할 여러가지 장점을 얻을 수 있습니다.

주석 작성과 코드 구현의 단계

책에서 추천하는 방식은 아래와 같습니다.

인터페이스 주석 작성 -> 메서드 본문 작성 -> 작성중 부족한 부분의 인터페이스 주석을 추가 -> 
메소드 본문 구현 완료 -> 메소드 구현 주석 작성

이런 방식으로 주석을 작성하면, 여러가지 장점이 있습니다.

1. 구현이 아닌 인터페이스 자체에 집중하여 주석의 질이 높아집니다.
2. 작성해 놓은 주석을 기반으로 구현을 하게 됨으로써, 스스로 구현의 문제점을 찾기 쉬워집니다.

주석은 설계 도구의 역할을 할 수 있습니다

주석을 먼저 작성하는 방식은 주석을 설계 도구 처럼 사용할 수 있습니다.

주석을 먼저 길고 자세하게 작성하게된다면, 그것을 작성하게 되면서 구현 전에 설계의 문제를 찾거나 설계를 조율할 수 있습니다.

또한, 주석을 작성하면서 인터페이스를 짧게 설명할 수 있으면 그 인터페이스는 간단하게 잘 정의되었다고 할 수 있습니다. 만약 주석이 길어진다면, 그 인터페이스가 충분히 추상화되지 않았다는 것을 의미합니다.

이러한 방식으로 주석을 먼저 작성하게 되면, 주석은 설계 도구의 역할도 하게 됩니다.

기존 코드를 수정할 때는?

주석을 코드 근처에 두어 코드 수정시 주석도 함께 수정될 수 있도록하자.

앞서 말했듯이 주석을 수정하는 것은 코드의 수정보다 훨씬 쉽습니다. 하지만 그 수정해야할 주석을 찾기 어려우면, 쉬운 수정조차 어려운 작업이 되어버립니다.

그럼 어떻게 해야할까요? 저자는 아래의 방식을 추천합니다.

• 주석을 코드 근처에 두어서, 코드 수정시 주석을 업데이트하는 것을 잊지 않도록 하기
• 커밋 메세지에 변경사항을 적지말고, 주석을 통해 코드에 문서화
• 주석을 단 한 곳에만 배치하여, 변경점이 있을 때 단 한 곳에서만 주석의 수정이 일어나게 하기
• 주석의 추상화 수준을 높여 사소한 수준의 변경이 주석에 영향을 주지 않도록 하기

위와 같은 방식만 지킨다면, 주석을 관리 및 수정이 매우 쉬워질 것입니다.

마치면서

A Philosophy of Software Design 다들 한 번씩 읽어보세요.

주석의 새로운 관점

여러 책을 읽어봤지만 이 책과 같이 주석의 중요성을 설명하는 책이 없었던 것 같습니다.
영어라는 압박이 있지만, 저자의 깔끔한 논리 전개가 놀라운 책이였고 매우 재미있게 읽었습니다.

모두에게 추천합니다!

막간 홍보

저는 현재 AUSG라는 동아리에서 활동하면서 다른 동아리원분들의 많은 발표를 듣고, 스터디에 참여하고 있습니다.

곧, AUSG 7기를 모집하니 많은 관심 부탁드립니다.