오픈소스 코드 문서화가 어려운 또는 쓸모 없는 이유

많은 개발자들이 Open Source Project에 참여하기 어렵다고 불평하는 것 중 하나가 문서화다. 방대한 코드에 버그를 수정하고 기능을 추가하는 일은 쉽지 않다. 그래서 Code에 대한 어느 정도 문서화나 안내서가 있으면 좋은데, 그런 문서를 찾기가 쉽지 않다. 있다고 하더라고 오래된 문서들이다.

왜 그럴까? WebKit Project에 참여하는 입장에서 생각해보면, 코드가 너무 빠르기 변경되기 때문에 문서화하기 어렵다고 이야기할 수 있다. 어느 정도 대략적인 문서화(요구사항 및 디자인 문서) 정도는 가능하지만, 실제 구현된 내용을 Class 수준으로 이야기하는 것은 어려운 일이다.  가능은 하지만, 글쎄, 한달 정도 지나면 Class 코드에 많은 부분이 변경되어 있을 것이다. 실제로 WebKit2의 Hardware Acceleration 코드인 Coordinated Compositing를 분석하고 문서화하려고 노력하고 있는데, 지난 몇 달간 없어진 Class도 있고 Class이름은 대부분 변경되었고, UI Process와 Web Process간의 message도 절반이상 제거되었다. 개발자들이 끓임없이 refactoring하기 때문이다. 일반 프로젝트에서는 refactoring은 잘 하지 않는다. 일단 기능이 구현되어 정상 동작하면 그만이기 때문이다. 하지만, Open Source Proejct는 다르다. 잘 동작하는 기능이라고 하더라도 좀 더 이해하기 쉬운 code를 만들기 위해서 끊임없이 Refactoring을 한다.

이런 상황에서 개발자는 code를 문서화하기 보다는 보다 이해하기 쉽고 간결한 code를 만들기 위해 노력한다. Class, variable, method이름 하나 하나가 제대로 지어졌는지 또 생각하고 의미가 명확한 이름으로 바꾸려고 노력한다.

오랜 시간을 들여 상세하게 문서화를 하려고 했던 나의 시도는 결국 실패하고 말았다. Code를 이해하고, 변경되지 않는 핵심 부분을 문서화 하는 것은 좋다. 하지만, 가장 좋은 문서화는 바로 쉬운 Code를 작성하는 것이다. 가끔 주석으로 설명된 문장들이나 그림들이 성경의 한 구절처럼 느껴질 때가 있는데, 이런 것들이 진정한 문서화 같다.

Source: https://joone-foss.blogspot.com/2013/03/blog-post.html