자체 문서화 코드

들어가기

개발하다 보면 코드에 주석을 달라는 말을 많이 듣는다. 이 말은 대부분의 코드는 이해 힘들기 때문에 코드에 대한 주석을
추가해서 코드 이해를 하기 쉽게 하기 위한 목적이다. 이 글은 코드를 이해하기 위한 시작에 대한 이야기이다. CodeCraft에서 재미난 주제로 다룬 내용이 있어서 여러 분과 공유하고 싶어서 정리해보았다.

작성자: ospace114@empal.com, http://ospace.tistory.com/

코드에 주석 달기

코드에 주석 달기는 매우 흔하게 하는 작업이다. 개발하는 과정에서 설계나 별도 문서가 잘 작성되어 있어서 주석이 필요없을지도 모른다. 그렇지만 현실에서는 그런 문서가 없을 가능성이 매우 높다. 또한 있다고 해서 거의 쓸모 없는 경우가 많고 코드가 오랜동안 유지보수된 경우 코드와 문서는 거의 일치하지 않을 경우가 많다.

코드와 문서를 일치시키는 일은 코드 작성보다 더 많은 시간이 소요될 수도 있다. 또한 문서 작성이 익숙하지 않다면 코드 보다 더 이해하기 힘든 문서가 작성될 수도 있다. 그렇기 때문에 코드에 주석을 다는게 그나마 코드에 가까이 있기 때문에 이해하기 바로 수정하기 쉽다.

그렇다고 해도 주석도 문서 작업의 일부로 변경 사항에 대해서 끊임없이 반영해야한다. 더욱 위험한 부분은 주석과 코드가 서로 다르게 되었다면 더욱 혼란을 일으킬 가능성이 높다. 그래도 코드에 주석을 다는게 최소한의 코드 이해하는데 도움이 된다.

문서화? 그딴거 몰라

대부분 일반적으로 코딩을 하게 되면, 난해한 축약어나, 이름을 많이 사용한다. 물론 암묵적인 약속과 주로 많이 사용하는 표현이 있을 수 있지만, 그 부분은 특정 분야나 트랜드에 의해 달라질 수 있는 부분이 많다.

아래는 일반적인 코딩을 작성하는 예이다.

int fval(int i) {
    int ret = 2;
    for(int n1=1, n2=1, i2=i-3; i2>0, --i2) {
        n1=n2; nw=ret; ret=n2+n1;
    }
    return (i<2) ? 1 : ret;
}

위의 코드를 보면 어떤 코드인지 바로 보고 알기 힘들다. 물론 익숙하다고 느끼는 분도 있다.
해당 함수는 피보나치 수을 계산하는 하는 함수이다.
각각의 변수의 역할을 이해하기 힘들다. 또한 줄 수를 줄이려고 짧은 코드 들는 한줄로 표현하고 있다.
만약 위의 코드를 보고 버그가 있어서 수정이 필요하다고 하면 코드를 이해하는데 있어서 시간이 많이 걸릴 수 밖에 없다.

문서화 써볼까?

앞의 코드를 좀더 문서화시킨 코드로 작성해보자.

int fibonacci(int position) {
    if(position < 2) return 1;
    int previousButOne = 1;
    int previous       = 1;
    int answer         = 2;
    for(int n=2; n<position; ++n) {
        previousButOne = previous;
        previous       = answer;
        answer         = previous + previousButOne;
    }
    return answer;
}

무었인지는 모르지만 코드가 눈에 보이는 느낌이다. 코드가 잘 읽혀진다. 물론 줄 개수가 많이 늘어났다.
그러나 주석이 거의 필요없을 정도로 코드의 가독성이 좋아보인다.
이런 형태를 자체 문서화 코드로 코드가 문서처럼 작성되서 코드 자체가 문서가 된다.

문서화 써보고 싶은데...

그럼 이런 자체 문서화 코드를 작성하고 싶다면 다음 같은 기준을 참고하기 바란다.

• 보기 좋게 만들어라
• 정상적인 경로 가시화
• 중첩 명령 지양
• 필요할 때 최적화
• 의미 있는 이름 사용
• 대상을 일관성이 있게 자연어로 표현
• 더 이상 나눠지지 않을 때가지 함수 분해
• 여러 일을 하는 함수 지양하고 함수 이름을 동작을 설명하듯 작성
• 묘사적인 타입을 사용(ex. C++ - unsigned int 대신에 size_t)
• 상수에 이름 사용 (Magic number를 지양)
• 중요한 코드 강조
• 클래스 public을 앞으로 중요하지 않은 코드 숨김
• 에러를 적절하게 핸들링(의미 있는 에러, 적절한 위치 처리)
• 의미 있는 주석을 작성(앞의 내용 적용하고 남은 것)

위의 기준에도 있지만 주석을 전혀 사용하지 말라는 의미가 아니다. 자체 문서화 코드를 작성해도 모호한 부분이나 자세한 설명이 필요한 부분이 있다면 주석이 필요하다.

잡다한 것: 문학적 프로그래밍

문학적 프로그래밍은 Donald Knuth이 제안한 프로그래밍 방법론 중에 한가지이다. 이 방법론은 프로그램을 코딩하는게 아닌 문서와 소스코드가 하나의 문서로 작성한다. 그리고, 작성한 문서에서 소스코드를 생성하여 컴파일하면 프로그램이 만들어지는 프로그래밍 방법론이다. 먼가 멋진 방법처럼 보인다. 새로운 관점을 제공하여 우리가 할일은 문서만 잘 작성하면 개발은 끝인 것 처럼 보인다. 그리고 문서 관리의 문제점을 해결하고 있다. 세부적인 내용이 자연스럽게 문서화되도록 유도하고 있다.
곁으로 보기에 이상적인 방법론으로 보이지만, 이런 문서를 작성하기 쉽지 않으며 컴파일 속도가 매우 느리고 문서를 쉽게 수정이 불가능하다. 또한 뛰어난 프로그래머들은 모두 작가가 될 수 없다.
문학적 프로그래밍의 대표적인 예로 프로그래밍 언어에는 파스칼이 있고, 문서화에는 Tex가 있다.

마무리

어떻게 보면 자체 문서화 코드는 코드의 가독성을 높이는 코딩 방식이라고 정의할 수 있다. 특히 간략하게 표현하는 형태를 최소화하고 가급적 단어를 그대로 사용하며 코드를 문장 형태로 완결되게 작성하라는 의미이다.

근데 문제는 대부분의 프로그래밍 언어는 영어로 되어 있어서 영어 표현이 원어민이 아닌 이상 잘 표현하기 힘들고, 또한 이미 작성된 영어 표현을 제대로 해석하기가 쉽지 않다라는 문제가 있다. 또한 자체 문서화 코드를 작성하다보면 코드 길이가 길어지고 한줄이 화면을 넘어갈 수도 있다. 배보다 배꼽이 커지는 상황이라고 할 수 있다. 그렇기에 필자는 이미 널리 알려진 약자나 단축어를 어느 정도 사용하고 있고, 함수 내에 임시로 사용하는 변수는 짧게 작성해서 사용하기도 한다. 추가로 최근에 함수형 프로그래밍 방식이 많이 사용되면서 코드가 더 난해해지고, 고급 표현을 사용하면서 더 함축된 난해한 코드가 사용된다. 이런 요인으로 인해 코드 자체를 문서화 형태로 작성하기 더욱 힘들어지고 있다.

그렇지만 여기서의 핵심은 가독성이 좋은 코드를 만들어야 추후에 유지보수가 쉬워지고 자신도 나중에 자신의 코드를 이해하기 좋게 되기 때문에 자체 문서화 형태의 코드 작성을 지향해야한다는 말이다. 역시 말은 쉽네요. ㅡ.ㅡ;;;;
부족한 글이지만 여러분에게 도움이 되었으면 하네요. 모두 즐거운 코딩생활 되세요.^^ ospace.

참고

[1] Pete Goodliffe, CodeCraft
[2] 문학적 프로그래밍, https://ko.wikipedia.org/wiki/%EB%AC%B8%ED%95%99%EC%A0%81_%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D