LangDev

문서화를 지원하는 언어

semmal

프로그래밍을 하다보면 문서화가 정말 중요하다는 점을 깨닫게 됩니다.

문서화는 전체 프로그램을 요약해서 소스를 처음보는 사람도 쉽게 그 의도와 구조를 파악하게 하고, 복잡한 모듈이나 함수를 간결하게 설명해줍니다.

지금은 Doxygen이나 Javadoc같은 도구를 써서 이런 문서화를 수행하는데, 이런 도구를 쓰려면 또다른 편집도구나 툴이 필요할 수 밖에 없습니다.

만약, 언어자체에 이런 문서화에 대한 요구가 반영이 된다면 어떨까하는 생각도 듭니다. 함수나 클래스, 오브젝트를 만들게되면 무조건 그에 대한 설명을 기입하게 만들거나, 컴파일의 결과로 소스에 문서화를 할 수 있는 주석을 생성해서 돌려주는 경우도 있을 수 있구요. 모든 것을 완벽하게 할 수는 없겠지만, 언어적으로도 현재 나와있는 툴 수준의 문서화는 기대할 수 있지 않을까요?

개인적으로는 Haskell의 LaTeX에 쓸 수 있는 확장된 소스가 맘에 들기는 합니다만, 정형화된 형태가 아니라 불만입니다. 이런 여타의 도구보다 더 발전된 형태의 문서화도구는 없을까요? 또다른 의견이 있으시다면 한번 들어보고 싶네요.

루비의 rdoc+파이썬 docstring이 좋을것만 같다는 막연한 생각.

(rdoc의 포매팅, docstring의 문맥별로 잘 붙일 수 있는 방식)

아겔-_-

저도 Python의 docstring이 참 편하더군요.

홍민희

Design by contract 대신 doctest 같은 것이 더 실용적이라는 생각도 해봅니다.

홍민희

doctest 정말 좋은데 좀 더 편의중심의 기준을 적용해주면 좋겠다는 생각도 들어요.

단순히 결과치가 뱉어내는 문자열을 비교하거나 하는걸로는 가끔 불편할때도 있고, 예외같은걸 적기에 붙여넣기 하는게 우울할때도;;;

아겔-_-

긁적... 참 재밌다고 생각하는건, 아주 오래전에 나왔을 리습의 docstring이나, 스몰톡에서 메서드나 클래스에 클래스브라우져등에서 문서를 붙이는 모습이나, 요즘 21세기에 들어서 이클립스 jdt에서 메서드위에 툴팁으로 뜨는 javadoc의 모습을 볼때 참 재밌는 세상이구나라는 생각이 드네요.

또, 그런 데자뷰처럼 되살아난 시간처럼 json, html5같은것들을 중심으로 뻗어나갈 마이크로포맷이나 그런것들의 부분을 보면, 텍스트 편집기로 왠만한것들을 해결하는것이 가장 원시적인 방법처럼 보이지만 뭔가 나름 인간적인 작업인건 아닐까 하는 착각도 들고요.(위지윅이나 보기 편하고 예쁘고 직관적으로 하는게 당연히 더 편리하고 좋겠지만, 이상하게도 자꾸만 편향을 갖고 그런쪽으로 흘러가는거 같은 느낌이 드네요.)

이상 잡상.

아겔-_-

역시 생각이 부족하니 글이 두서가 없네요.

rdoc은 javadoc과 비슷한 것 같은데, docstring은 개념은 좋지만 역시 일반 주석과 다를 바가 없는 것 같습니다.

정리는 안되지만, 제 생각을 조금 더 풀어내자면, 문서화도 프로그래밍으로 볼 수 있지 않은가 하는 겁니다.

워드에서 상용구는 변수에 문자열을 대응시킨 것이죠. 그래서 문서화의 Copy&Paste도 프로그래밍처럼 더 편하게 만들 수 있으리라 생각합니다.

문서화를 하면서 프로그래밍상의 변수를 정의하고 그 변수가 문서화에서도 쓰이고 프로그램 소스 내에서도 쓰이는 거지요. 같은 방법으로, 문서화를 하면서 함수를 정의하고, 그 함수가 문서화에서도 쓰이고 프로그램 소스 내에서도 쓰이는 거지요.

문서화를 위한 클래스를 상속받기만 하면 그 서브클래스는 자동으로 문서화가 되거나 하는 방법도 생각할 수 있을테구요.

제대로 제 의도가 전달이 되는지 잘 모르겠네요.

semmal

어떤 함수 f의 docstring은 f.__doc__처럼 접근이 가능한것처럼 reflective한건가봐요?^^

아겔-_-

흠... 간단히 예를 들어보는게 좋을 것 같아요.

/* {foldr.name}은 아래와 같이 정의된다.
[code]{foldr.definition}[/code]
{foldr.arg[0].name}의 타입은 {foldr.arg[0].type}이고 ... 중략...
예제: {?foldr (+) 1 [1..10]}
*/

이렇게 적으면

/* 함수 foldr은 아래와 같이 정의된다.
    foldr f z []      = z
    foldr f z (x:xs)  = f x (foldr f z xs)
f의 타입은 a -> b -> b이고 ...중략...
예제: 
    > foldr (+) 1 [1..10]
    56
*/

이렇게 나온다는 거죠. 당연히 소스안에 들어있는 주석이구요.

제가 생각하고 있는 개념에서 아주 간단한 예제일 뿐이구요. 다른 분들의 아이디어와 합친다면 상당히 재밌는 방법도 많이 나올 것 같아요. 아예 주석이라는 문법이 없을 수도 있지 않을까하는 생각이 들기도 하구요.

만약 정의가 잘 된다면 랑데부 전체 이름으로 논문을 내보는 것도 좋을 것 같구요 후후

semmal

아항~ 문서 안에서 다른 문서에 대한 참조나 이용이 가능하고, 코드에서도 실행시간에 접근이 가능하겠군요?

문서는 실행과 구분되어야 한다는 고정관념을 깨시는 부분도 보이는게 예제에 대해서 실행내역을 직접 실행해서 생성해주네요? 멋지삼/ (물론, 저걸 doctest처럼 이용하지도 못하고, 부수효과등에 묶인 대상에 대해서는 어렵겠지만)

아겔-_- 
/* {!{{?foldr (+) 1 [1..10]}.test}==56} /*

이렇게 된 소스를 실행했을 때

Trying... foldr (+) 1 [1..10]==56
ok

이렇게 되면 좀 비슷하려나요? 좀 억지스럽기는 하네요 쿠쿠

semmal

뭐 어차피 코드가 다 들어갈수있다면 테스트케이스까지는 어려워도 assertion들도 넣을수있을테고 그런작업만을 위한 라이브러리나 그런걸 만들어서 더 멋진 방법으로 작성할수있겠죠.

테스트에 대한 더 멋진 방법이 되겠군요. ^^

아겔-_-

Doxygen이나 Javadoc을 보면 참 멋지죠. 하지만, 수년간 개발을 하면서 느꼈던건, 클래스/함수에 대한 명세서나 클래스 다이어그램 같은 구조에 대한 문서가 갖는 중요도는 해당 소프트웨어가 어느 부분에 속해있느냐에 굉장히 의존적이라는 점입니다.

API나 라이브러리 같은 경우에는 Doxygen이나 Javadoc이 굉장히 강력한 힘을 발휘할 수 있는 부분입니다. 레퍼런스를 생성하는 용도로는 가히 최고이니까요. 하지만, API나 라이브러리를 위해 가장 필요한 문서는 예제코드라고 생각합니다. 이건, MSDN과 ADC에서도 찾아볼 수 있는 차이점이지요. MS의 MSDN은 상대적으로 레퍼런스가 강하지만, Apple의 ADC는 상대적으로 예제가 강합니다. 일장일단이 있지요. ADC의 예제들은 첫눈에 알아보기 쉽고 써먹기도 딱 좋은데다, 포럼에 올리면 예제를 잘 만들어서 업데이트 해준답니다. 반면에, 반환코드값이라든지 각 입력 변수를 어찌 사용해야하는지는 찾아보기 좀 어렵습니다. MSDN은 반대겠지요. :)

반면에, 비지니스 로직이나 실제 구동되는 어플리케이션에서 Doxygen/Javadoc으로 대표되는 문서화 기법은 의미를 잃어버립니다. 구조/기능에 대한 문서화도 중요하지만, 흐름에 대한 문서화가 더욱 절실해지니까요. 흐름, 즉 Flow Diagram이나 Collaboration Diagram이 갖는 중요도는 더욱 높아집니다. 그리고, 소프트웨어가 복잡해질수록 Class Diagram보다는 Component Diagram이 갖는 중요도가 더 커진다고 생각됩니다. 이 방면에서는 세부적인 명세서는 큰 의미가 없다고 생각합니다. 전체적인 그림을 잘 그려주고, 포인트를 잘 짚어준 뒤, 네이밍이 잘된 깔끔한 코드를 제공하는 것만으로도 충분하다고 봅니다. (물론, Doxygen/Javadoc으로 작성된 레퍼런스를 제공한다면 더욱 좋겠지만요.)

이런 이유로, 전 기존의 클래스/함수에 관심을 두는 문서화 기법보다는 코드의 실행흐름에 집중하는 문서화 기법이 필요하다고 생각하는 중입니다. profiling을 통한 flow diagram의 자동생성 같은거랄까요? :) call graph도 비슷한 역할을 하겠지만, 형식이 그래서야.. 알아보기가 머리아픕니다. T_T

아.. 쓰다보니 쓰레드와 좀 다른 방향으로 흘러가버렸군요... =3===3

까막

API나 라이브러리를 위해 가장 필요한 문서가 예제코드라는 데는 동의합니다. 그래서 테스트와 예제코드 문서화를 같이 진행할 수 있는 도구가 제가 쓰고 있는 대부분의 언어에서 제대로 지원되었으면 좋겠습니다.

Flow와 Collaboration Diagram이 가장 발전한 모양은, 아마도 가장 추상이 잘 된 코드가 아닐까 생각합니다. 물론 복잡한 로직이라면 반드시 어느정도의 설명이 붙어야하겠지요. 하지만 이정도는 다이어그램이 아닌 일반적인 주석으로도 충분하다고 봅니다.

아무리 좋은 Flow 분석 자동화 툴이라도 못생긴 코드를 분석하면, 제대로 된 결과가 나올리가 없지 않을까요? 또, 예쁜 코드는 굳이 좋은 툴이 없어도 그 내용을 쉽게 파악할 수 있지 않을까요? 그런 생각이 드네요.

semmal

전반적으로는 동의하지만, 다이어그램의 가치에 대해서는 약간의 견해 차이가 있는듯 합니다.

코드는 일종의 글이라고 볼 수 있습니다. 그리고, 아무리 글을 잘 써서 정리를 하더라도, 잘 그린 다이어그램보단 표현력이 떨어지는 것은 사실이죠. :) 무엇보다 한눈에 들어온다는 점이 시각적 표현의 장점이라고 생각합니다. 아무래도 코드는 흐름을 쫓아가며 읽어야하기 때문에 한눈에 들어오지는 못하지요. 그리고, 코드를 읽는 시간보단 그림을 읽는 시간이 빠를겁니다. 이 점이 제가 잘 작성된 (잘 추상화된) 코드가 만능이 아니라고 생각하는 이유입니다. (고백하자면, 사실 저는 코드만능주의자였습니다. 심지어는 주석도 필요없다고 생각했었지요.)

물론, 복잡도가 심하지 않으면 다이어그램 없이 코드만으로도 충분하겠지만, 복잡해질수록 다이어그램이 필요해지는 것도 사실입니다.

마지막으로, 못생긴 코드를 분석하면 못생긴 그림이 나온다는 점에는 전적으로 동의합니다. 이 점에 착안해보면, 작성된 코드가 얼마나 못생겼는지 순식간에 확인하는 방법으로 활용될 수도 있을거라는 생각이 드는군요.

좋은 지적 포인트 감사합니다. :)

까막

CWEB은 어떻게 생각하십니까?

초천재

CWEB은 잘 모르는데 대충 개념만 설명 해주시겠어요?

semmal

http://faq.ktug.or.kr/faq/CWEB

문서가 문서참조도 하고, source가 source 참조도 하지요.

그래서 이름도 문서화 프로그래밍(혹자는 문학적 프로그래밍이라고 한다지만... : Literate Programming)

문서화도 programming으로 볼 수 있지 않냐는 물음에는 가장 근접할 듯 싶습니다.

C programming에 쓸 수 있도록 한 것이 CWEB인데 제가 이걸 실전적으로 쓰는 것을 본 것은 'STL Tutorial & Reference Guide' 뿐이었다는...

'Literate Programming' 어디서 구할 수 있으려나?... 예전에 kangcom 원서 떨이할 때. 금방 나갔던 기억이... 쳇, 내가 잽사게 샀어야 했는데... 지금은 amazon에서도 paperback 뿐이라는...

김우승