문서화 되지 않는 프로그램의 문제는 이렇다.
흔히 프로그래머는 문서(혹은 주석)에 HOW는 기술하지만 WHY는 기술하지 않는 다.
그리고 이렇게 말한다. "자세한 내용은 코드를 보라."
코드는 how(어떻게 동작하는 가?)는 알려 주지만
why(왜 이렇게 만들었는 가? 이것의 의도를 무엇인가? 목적은?)는 설명해 주지 못한다.
다음에 문서를 읽을 사람은 그들은 운영자이거나 후임 개발자이지
산업스파이나 경쟁업체의 reverse engineer가 아니다.
난 가끔은 지저분하게 자질구레한 내용까지 주석에 적기도 하는 데.
답글삭제어떤 사람은 이렇게 말한다.
"자꾸 소스 코드를 더럽히지 말고 깔끔하게 정리해."
하지만 내 생각은 이렇다.
필요없는 내용은 후임자가 필요없을 때 정리하면서 지울 수 있지만
안 적어준 내용은 후임자가 필요하다고 해서 만들어 낼 수가 없다.
울 회사의 어떤 주석에는 다음과 같이 적혀 있다고 한다.
답글삭제"이 코드는 보안상 매우 중요한 코드이기 때문에 문서화를 하지 않아야 한다."
완전히 코메디인데. 그렇게 중요한 코드인데. 회사 사람이면 아무나 볼 수 있는
곳에 던져놓았다는 것도 웃기고 저 논리라면 우리나라 국가 1급 기밀 문서에는
모두 다음 한 문장만 적혀 있어야 한다.
"이것은 너무 중요한 내용이기 때문에 기밀문서에 적지 않았다"
잘 적어두고 꼭 필요한 사람만 볼 수 있게 권한 설정을 해둬야지
아예 안 적어두면 어떻게 하자는 말인가?
결국 핵심 개발자 몇 명이 회사를 떠나면 이런 회사는 어려움을 겪게 된다.
아이러니하게도 문서화를 잘 하지 않는 개발자가 더 훌륭한 개발자로 인식될 수도
답글삭제있다.
왜냐하면 후임자가 프로그램을 맡았을 때 문제가 발생했는 데 문서화 부족으로 해결을 못하고 있다면 다시 전임자가 불려오는 데.
그 때 전임자가 멋지게 문제를 해결하면 사람들은 이렇게 생각한다.
"음.. 전임자가 맡았을 때는 아무 문제 없었는 데. 후임자가 맡은 뒤로 문제가 커졌군. 전임자가 후임자보다 역량이 뛰어난 사람인가봐."
사람들은 이런 환경에서 문서화에 신경을 쓸 이유가 없다.
답글삭제문서화를 잘 할수록 자신의 능력을 드러낼 기회도 줄어들고
후임자에게 밀려서 자리를 잃을 수 있다고 생각하기 때문이다.
그리고 문서화에는 많은 시간을 소비해야 되서 단기적으로 봤을 때
코드 생성 속도가 느려진다.