Thoughts2009.09.22 10:28

얼마 전에 코드 공동 관리에 대한 재미있는 외국 사례를 하나 들었습니다.

코드를 관리하다보면 항상 골치가 아픈 부분 중에 하나가 코멘트(comment)입니다. 즉 주석 관리를 어떻게 하느냐 하는 것인데요.

이 회사 직원들은 개발을 몇 줄 혹은 얼마나 했느냐에 따라서도 포상을 받지만, 주석을 얼마나 정확히 달았느냐, 얼마나 많이 달았느냐에 따라서도 포상을 받습니다.

함수의 사용 방법을 적는 것은 물론이고, 함수를 호출하는 함수의 목록, 함수 호출 결과로 발생하는 side-effect의 목록, 함수 호출 시 발생할 수 있는 예외 상황, 그리고 함수에 전달되는 인자의 의미 등등을 전부 적습니다. 그러다 보면 주석문의 길이가 길어집니다. 이 회사 직원들은 주석도 평가와 포상의 대상이 된다는 사실을 알기 때문에, 아주 적은 양의 코드에도 아주 자세한 주석을 답니다.

그리고 주석과 실제 코드에 불일치를 발견한 사람에게는 가산점을 줍니다. 종종 주석이 제대로 업데이트 되지 않아 문제가 되는 경우를 많이 보게 되는데, 그런 문제를 포상체계를 통해 해소하고자 하는 것이죠.

주석을 포상과 직접적으로 연결한다는 아이디어는 얼핏 생각하면 좀 졸렬하기도 합니다만, 직원의 적극적인 참여를 이끌어 낼 수 있다는 점에서는 긍정적으로 생각됩니다.

이 이야기를 다른 사람들하고 좀 했더니, 주석 라인수를 생산성 기여도에 그렇게까지 많이 반영하는 것은 무리가 있지만, 가중치와 결합된 마일리지 체계를 도입해서 포상을 하면 긍정적일 수 있겠다는 데는 모두들 동의를 하더군요.

문서와 코드의 일치는, 언제나 문제가 되면서도 좀처럼 해결이 되지 않는 부분입니다. 이런 부분을 해결하기 위한 바람직한 방법을 항상 고민할 필요가 있다고 생각합니다.

신고
Posted by 이병준

소중한 의견, 감사합니다. ^^

  1. 재밌네요. 혹시 정확한 출처를 알 수 있을까요?

    2009.09.22 13:53 신고 [ ADDR : EDIT/ DEL : REPLY ]
  2. 정동인

    안녕하세요. 블로그 잘 보고 있습니다.
    주석을 잘 다는게 코드를 잘 짜는거라고 배웠다가, 또 어딘가에서는 (어디서였는지 기억은 안나네요)
    주석이 필요 없는 코드를 짜라 (의미가 분명한 코드를 짜라는 거겠죠?)고 해서
    그렇게 믿고 주석을 최대한 안달려고 애쓰고 있는데,
    주석을 최소한으로 다는 것과 최대한으로 다는 것은 이상과 현실의 차이일까요? 아니면 케이스에 따라 다르게 생각해야 하는 걸까요?
    항상 막연하게 궁금해 했던 문제인데, 포스트를 보고 질문드려 봅니다.

    2009.09.23 09:27 신고 [ ADDR : EDIT/ DEL : REPLY ]
    • 저는 어떻게 생각하냐면... 주석은 문서의 일부라고 생각합니다. 실제로 많은 분들이 주석에서 생성된 Javadoc을 보고 코딩하고 있구요. 문서와 코드 간의 불일치는 반드시 해소되어야 합니다. 그리고 문서는 코드의 현 상태를 반드시 반영해야 합니다. 저는 Java SE의 Javadoc 다큐먼트가 모든 프로젝트 결과물 문서가 갖추어야 할 이상적인 모습이라고 생각합니다. 특히 코드를 보여주면 안되면서도 그 사용자가 우아하게 통합할 수 있는 라이브러리를 디자인하는 경우에는요.

      협업을 통해 프로그램을 개발하는 경우에는 주석보다는 '의미가 분명한 코드'가 더 효과적일 수 있습니다. 하지만 개발 결과물을 배포하는 시점에서는 좀 다르게 생각해 봐야 한다는 뜻입니다.

      2009.09.23 10:30 신고 [ ADDR : EDIT/ DEL ]
  3. 정동인

    답변 고맙습니다^^

    2009.09.23 10:57 신고 [ ADDR : EDIT/ DEL : REPLY ]
  4. 주석이 중요하단점을 근례에 들어서 많이 느끼고 있습니다..
    예를들어 한참전에 만든 코드를 다시 확인하려는데 이해못하는경우와, 다른이의 코드를 분석하는데 주석이 없어서 이해하는데 시간이 걸리는경우...
    전자의 경우 이전에 자신이 직접 만들어서 스타일이 확바뀌지 않는이상 이해하는데 어려움은 없습니다만,
    후자는 예기가 달라지는거죠

    2009.12.21 12:38 신고 [ ADDR : EDIT/ DEL : REPLY ]