문서화

04 | 문서화
진실을 말하는 것은 쉽다. 그러나 거짓말을 잘하려면 센스가 필요하다.

_사무엘 버틀러 Samuel Butler
종종 잘못된 문서화는 아예 문서화를 하지 않은 것보다 더 나쁜 결과를 초래한다.

_베르트랑 메이어 Bertrand Meyer
컴퓨터는 주석과 문서화 부분은 무시한다. 따라서 온 힘을 기울여 주석과 문서화를

활용한다면 불쌍한 유지보수 프로그래머를 좌절시킬 수 있을 것이다.

주석에 거짓말을 추가하라

적극적으로 거짓말을 할 필요는 없다. 그냥 자연스럽게 주석을 업데이트하지 않아 내용이 맞지 않는 것처럼 보이게 하자.

명백한 사실을 문서화하라

코드에 /* add 1 to i */와 같은 양념을 추가한다. 중요한 점은 패키지나 메소드의 전체 목적과 같은 어려운 부분은 절대 문서화하지 않는다는 사실이다.

이유는 빼고 “어떻게”에 대해서만 문서화하라

프로그램이 무엇을 하는지에 대한 세부 사항 그리고 프로그램이 무엇을 달성하지 않는 것인지에 대해 문서화하라. 버그가 생기면 수정을 담당하는 프로그래머는 해 당 코드가 무엇을 수행해야 하는지 알 수 없게 된다.

“명백하게” 문서화하지 말아라

예를 들어, 항공기 예약 시스템을 구현하고 있는데 다른 항공편을 추가하려면 25군데를 수정해야 한다고 가정하자. 물론 어디를 수정해야 할지를 문서화하면 안 된다. 나중에 누군가 우리 코드를 수정하려면 전체 라인을 완벽하게 이해해야만 원하는 수정을 할 수 있을 것이다.

문서화 템플릿의 적절한 활용

함수 문서화 프로토타입을 이용해 자동으로 코드에 문서화 틀을 제공할 수 있다. 이때 다른 함수(혹은 메소드나 클래스)에서 복사해서 사용하고 절대 필드에는 문서화 틀을 사용하지 말아야 한다. 어쩔 수 없이 필드에 문서화 프로토타입을 사용해야 한다면 모든 함수에서 같은 파라미터 이름을 사용하도록 하고 주의사항도 같게 하자. 물론 이 주의사항이 현재 함수와 전혀 관련이 없는 것일수록 좋겠다.

디자인 문서의 적절한 활용

상당히 복잡한 알고리즘을 구현해야 할 때는 코딩을 하기 전에 디자인을 확실하게 해야 한다는 고전 소프트웨어 엔지니어링 원칙을 지켜야 한다. 상당히 복잡한 알고리즘의 각 단계에 대한 설명을 포함할 수 있도록 매우 세밀하게 디자인 문서를 작성한다. 이 문서를 세부적으로 만들수록 좋다.

디자인 문서에서 알고리즘을 구조화된 여러 단계로 나눠서 각 문단에 자동으로 계층적인 번호를 추가할 수 있다. 헤딩은 적어도 5단계로 만들자. 가능하면 구조를 잘게 나눔으로써 최종 결과물이 나왔을 때 500개가 넘는 문단에 자동으로 번호를 추가할 정도가 돼야 한다. 다음은 실생활에 사용하는 어느 문단의 예다. 1.2.4.6.3.13 - 선택한 마이그레이션을 적용했을 때 발생하는 모든 효과를 표시하라 (간단한 의사코드는 생략).

그리고... (이제 본격적인 혼란의 세계로 빠져든다) 코드를 작성할 때는 각 문단에 대응하는 전역 함수를 만든다.

Act 1_2_4_6_3_13()

디자인 문서에 나와 있으므로 위할 수에 대한 문서화는 따로 필요치 않다!

디자인 문서의 번호는 자동으로 매겨지는 것이므로 변경이 발생했을 때 이를 일일 이 코드에 반영하는 것은 정말 어렵다(함수명은 자동으로 변경되는 것이 아니므로. 그럼 큰일 아닌가? 우리는 문서를 최신으로 유지하지 않으면 되므로 걱정할 것 없다. 오히려 문서 추적에 필요한 사항을 모두 파괴하는 것이 좋다.

운이 좋다면, 우리의 뒤를 이어 작업할 사람은 지금은 멸종한 286 컴퓨터와 먼지 다 수북이 쌓여있는 창고 선반 뒤에 숨겨진 앞뒤가 맞지 않는 초안 한 두 개를 건질 수 있을 것이다.

측정 단위

인치, 피트, 미터와 같은 측정 단위를 변수, 입력, 출력, 매개변수에 문서화는 절대 하지 않는다. 이는 엔지니어링 작업에서 매우 중요한 요소다. 마찬가지로 변환 상 수의 측정 단위나 값이 어떻게 전달되는지 등도 문서화하지 않는다. 주석에 잘못된 측정 단위를 슬쩍 넣는 것은 유치하지만 효과적인 방법이다. 좀 더 사악한 방법을 원한다면 자기 자신만의 측정 단위를 만들어 보는 방법도 있다. 자신의 이름이나 다른 아무개 이름을 사용하고 해당 단위에 대해 정의하지 않는다. 누군가가 우리의 작업 방식에 이의를 제기한다면 소수점 연산보다 정수 연산을 잘 할 수 있도록 그렇게 한 것이라는 등의 동문서답을 이용하자.

문제점

코드의 문제점을 문서화하지 않는다. 클래스에 버그가 있을 수 있다는 사실을 발견했으면 혼자만의 비밀로 간직한다. 코드를 어떻게 재조직하거나 재작성해야 할지 아이디어가 떠올랐을지라도 문서로 남겨놓지 않는다. 영화 밤비 Bambi에서 귀염둥이 호감 퍼 Thump er의 말을 기억하자. “좋은 말을 하지 않으려거든, 그 입 닫으라.”. 코드를 만든 프로그래머가 우리의 주석을 보고 어떻게 생각하겠는가? 회사 사장이 본다면? 고객이 본다면? 심지어 해고될 수 있다. “수정해야 함!”이라는 익명의 주석을 활용할 수 있다. 특히 이 주석이 어느 부분을 가리키는 것인지 명확하지 않을 수 록 좋다. 내용을 되도록 흐지부지하게 만들어서 누군가를 비난하고 있다는 느낌이 들지 않도록 주의해야 한다.

 

변수 문서화

변수 선언에는 절대로 주석을 달지 않는다. 변수를 어떻게 사용해야 하고, 경곗값 은 무엇이며, 사용할 수 있는 값은 무엇이고, 함축된/표시된 십진수 점, 측정 단위, 표현 형식, 데이터 입력 규칙(전체 값을 채워야 하는지, 반드시 입력해야 하는지 와 같은), 값을 신뢰할 수 있는 조건 등과 같은 정보는 코드를 통해 충분히 얻을 수 있다. 주석을 기록하도록 상사가 강요한다면 메소드 바다에 변수를 넣어서 사용하자. 그러나 이 경우에도 절대 임시로라도 변수 선언에 주석을 추가하면 안 된다.

깎아내리는 말을 주석에 사용하기

외부 회사와 유지보수 계약을 체결할 수 없도록 다른 소프트웨어 선도 업체를 헐뜯는 글을 추가한다. 특히 현재 회사와 계약할 수 있는 가능성이 있는 회사를 공격 할수록 좋다.



펀치 카드의 코볼(CØBØL)을 사용한 것처럼 주석을 추가하라

개발 환경 분야의 발전 특히, SCID 등의 사용을 거부하라. 모든 함수와 변수 선언 이 한 번의 클릭으로 가능할 것이라는 헛소문에 현혹되지 말자. 비주얼 스튜디오 6.0으로 개발한 코드를 Edlin이나 vi를 사용하는 개발자가 유지보수할 것이라 가 정하자. 드라콘 식의 주석 규칙을 따르는 것이 소스 코드를 올바로 작성하는 것이라는 신념을 갖자.

몬티 파이선 주석

makeSnafucated라는 메소드에는 /* make snafucated */과 같은 자바독JavaDoc 주석을 추가한다. 어디에도 snafucated의 의미를 정의하지 않는 것이 핵심이다. snafucated의 의미를 모르는 사람은 바보임이 틀림없다. Sun AWD 자바족에는 이와 같은 기법을 사용한 고전 예제가 많다.