all about documentation Dec 22, 2008

http://lwn.net/Articles/310569/

커널 개발자들은 documentation에 대하여 굉장히 회의적이다.
Andrew의 말이 인상적이다.

"코드를 clear하게 만드는 것 보다는, 아무생각없이 단지
여기에 주석을 넣기로 되어 있으니...."

이미 TDD와 같은 방법론에서는 주석을 Andrew와 같은 이유로 주석을 금기시하기도 한다.
하지만, 어디까지나 저건 이미 guru의 반열에 오른 커널 developer들의 이야기이다.

사실, 커널 code를 exploration할 때 중간중간 주석이 없으면 굉장히 이해하기 어려운 부분들이 많이 있다. 물론 obsolete한 주석들도 많이 있긴하다. 하지만 그런 주석들로 인하여 긴 항해에서 방향을 잃지 않을 수 있을 때가 더 많이 있다는 것이 내 경험이다. 특히 kernel core 쪽은 단순한 logic이 아닌, 특정 machine에서 발생했던 regression들로 인하여, 이상한 magic code들이 들어가 있기도 하다. 이것은 커널 patch history를 follow up하지 않고 있으면 logic 상으로는 도저히 이해할 수 없는 코드들이다.

요즘은 Andrew를 비롯한 많은 kernel developer들이 git의 log의 중요성을 강조하고 있어, 문제를 보다 명확하게 logging을 하려고 하고 있어 대체적으로 만족할 만한 수준이다.

어쩌면, 나와 같은 kernel newbie들도 그런 주석에 고마워해야 할 게 아니라, 주석들로 인하여 clear되지 않고 있는 코드들에 질타를 던져야 하나...