코드 문서화 생산성 향상 / 손실에 관한 연구

많은 검색을 한 후에, 나는 소프트웨어 개발 세계에서 알려진 가정과 관련된 기본적인 질문에 대답하지 못했습니다 :

알려진 사항 :

적절한 코드 문서화 (Doxygen 태그, Javadoc 또는 단순히 주석이 많음)에 대한 엄격한 정책을 시행하면 코드 개발에 시간이 많이 걸립니다.

그러나:

철저한 문서화 (또는 API)는 기능을 추가하거나 버그를 수정하는 숙련 된 신규 개발자에게 생산성 향상 (한 가정)을 가져옵니다.

질문:

개발 속도가 길어짐에 따라 생산성이 향상됨 (엄격히 경제적 인 의미)으로 이러한 문서 오프셋을 보장하는 데 추가 개발 시간이 필요합니까?

나는 그 결론을 뒷받침하는 객관적인 증거를 가져올 수있는 사례 연구 또는 답변을 찾고 있습니다.

미리 감사드립니다!

기사 "표기 스타일은 더 화장품보다"오히려 오래 그러나 그것은 매우 흥미 롭군요 : http://portal.acm.org/citation.cfm?id=78611 .

오래되었지만 요즘 가능한 모든 멋진 것들을 포함하지는 않지만 코드 문서 가 중요 하다는 것을 분명히 보여줍니다 .

저와 같이 ACM 디지털 라이브러리에 액세스 할 수없는 사람들을 위해 두 그룹의 프로그래머를 만들고 같은 코드를 연구하도록했습니다. 그룹 A는 일반적인 주석이 포함 된 코드 만 받았으며 그룹 B는 목차, 상호 참조 및 1990 년에 가능했던 모든 장점을 갖춘 인쇄 된 목록을 받았습니다.

그런 다음 두 그룹에 코드에 대한 특정 작업 (예 : 기능 확장, 버그 찾기 등)을 수행하도록 요청하고 답변의 속도와 품질 측면에서 점수를 매겼습니다.

그룹의 균형을 맞추기 위해 그들은 같은 수의 전문가 및 주니어 프로그래머를 가졌습니다.

글쎄, 그룹 B (정말로 인쇄 된 목록을 가진 그룹)는 수많은 테스트에서 그룹 A보다 일관성있게 점수가 높았습니다. 그리고 특정한 경우에, 그룹 A의 가장 전문가들만이 그룹 B의 주니어 프로그래머를 능가했습니다.

이 기사는 더 많은 것을 말하지만 이것이 메모리에서 다시 수집 할 수있는 것입니다 (아직 어딘가에 인쇄 된 기사가 있어야합니다).

적어도 저에게는 읽기 쉬운 코드 가 잘못 작성된 코드를 보완하는 문서보다 훨씬 가치가 있다는 것이 분명합니다 . 코드를 다시 작성하여 주석을 제거하고 더 자기 설명을 할 수 있는지 확인하기 위해 코드의 주석을 도전으로 생각하는 경향이 있습니다.

나는 상식을 제외하고는 확실한 증거로 그것을 뒷받침 할 수 없습니다.

인용 할 연구가 없지만 간단한 규칙이 있습니다 .2 주 후에 코드로 돌아와서 내가 한 일을 즉시 알아낼 수 없다면 더 많은 의견이 필요하거나 단순화해야합니다. .

물론, 어떻게 코드의 작품은 코드 자체로 문서화되어야한다. 그러나 시간이 신중하고 간결하게 설명 쓰기 코멘트를 보냈다 이유 코드가 코드를 유지하고있는 유일한 사람하더라도, 그것은 거의 확실히 장기적으로 자체에 대한 지불 방법을 기록됩니다.

소프트웨어의 수명은 대부분 유지 관리 단계에서 소비되므로 개발자가 발생하는 상황을 이해하는 데 도움이되는 프로그래머는 개발자가 더 빨리 속도를내는 데 도움이되므로 거의 확실하게 재정적 수익을 제공 할 것입니다.

약간 사소한 문서화가 아닌 API에서 코드의 API는 거의 쓸모가 없습니다. API의 힘은 개별 메소드 / 객체의 작동 방식이 아니라 전체 단위로 함께 작동하는 방식에서 비롯되기 때문입니다.

따라서 실제 문서보다 더 유용한 것은 API의 예상 사용 패턴과 API의 대다수 (100 %가 아닌)를 사용하는 몇 가지 명백한 상황을 해결하는 방법을 설명하는 요리 책과 유사한 문서입니다.

주어진 방법이 아직 발명되지 않은 도구가 없는지 여부에 대한 결정은 문서 작성 을 요구 하기에는 너무 주관적 입니다.

"모든 퍼블릭 메서드"또는 특정 패키지의 모든 클래스 등과 같은 베스트 추측 관행은 특정 사용 사례를 넘어서는 권장 할 수 없지만 너무 거칠 수 있습니다.

내 제안 : 개발자에게 모범 사례, 문서화에 중요한 메소드 (공식 또는 비공식 API, 일반적으로 사용되는 스텁 메소드, 복잡하거나 난해한 방법)를 식별하고 스스로 통제하도록하는 방법을 가르치십시오.

(밀접하게 관련 : 코딩 표준에 너무 많은 균일 성이있을 수 있습니까? )

^{나는 인용 할 연구가 없지만 사과를 시도하지만, 그것을 측정하려는 시도가 일반적인 결론을 도출하기에는 너무 큰 결과에 영향을 줄 수있는 문제라고 생각합니다.}

이런 점 에서 "일반"코드와 퍼블릭 API 를 분리 해야한다고 생각합니다 . 정규 코드의 경우 해당 코드 의 다른 응답자 대부분 이 자체 문서화되어야하며 거의 산문처럼 읽혀 져야합니다 . 내 코드가 그렇지 않으면 일반적으로 내 잘못이므로 문서화하는 것이 아니라 리팩터링해야합니다. 작은 방법 , 추상화의 단일 레벨에서 작업하는 정확하고 설명하는 이름을 가진, 한 번에 하나의 일을은 이것을 달성을 향한 큰 길을 갈 수 있습니다.

주석의 문제점은 썩었다는 것입니다. 주석을 추가하자마자 주석이 첨부 된 코드와 독립적으로 생활을 시작합니다. 코드를 수정 한 다음 개발자가 관련 주석도 제대로 업데이트 할 가능성은 얼마나됩니까? 내 경험상 0에 가깝습니다. 몇 가지 수정 후 최종 결과는 댓글이 사람들을 도와주는 대신 당황하게하거나 오도하는 것입니다.

가능한 예외는 성능 최적화 코드 또는 특정 알고리즘 사용 입니다. 이 경우 코드가 왜 보이는지, 알고리즘에 대한 참조 등을 설명하는 주석을 추가하는 것이 유용합니다.

이 주제에 대한 주요 작업은 Clean Code 입니다.

OTOH 공개 API는 Javadoc 에서도 잘 문서화되어야합니다 . 그것은 매우 다양한 기술과 가정을 가진 무수한 총 낯선 사람들이 사용할 수 있기 때문에 가능한 한 간단하고 명확하게 사용하기 위해 예방 조치를 취해야합니다. 그것은 여전히 ​​적절한 API 디자인의 문제이지만 문서화에도 중요한 역할이 있습니다.

문제는 코드를 문서화하여 모든 후속 개발자가 수행하는 작업을 파악해야하는 시간을 절약 할 수 있는지 여부입니다. 코드가 수행하는 작업에 대한 질문을 제기하지 않고 코드 검토를 통해 코드를 작성하는 경우 올바른 모양 일 수 있습니다. 입력에 대한 가정을 설명하는 것은 그리 어렵지 않습니다. 메소드가 정수 오브젝트를 가져 와서 문자열 오브젝트를 리턴한다고 가정하십시오. int가 null 일 수 있습니까? 정수 / 최소값 (정수. 최소값 / 최대 값 제외)이 있습니까? 빈 문자열 또는 null을 반환 할 수 있습니까? 예외가 발생합니까? 물론 누구나 검사를 통해이를 찾을 수 있지만, 충분한 다른 개발자가 코드를 사용하려는 경우 몇 분마다 시간을 절약하는 것이 좋습니다. 또한 테스터에게 코드를 확인하기위한 테스트 작성에 도움이됩니다.

개발자가 문서를 작성하거나 유지 관리하는 데 시간을 소비해야하는지 여부에 대해 항상 논쟁의 여지가 있었지만 실제로 개발자가 자신보다 코드를 다시 방문 할 때 코드를 잘 작성하고 주석을 달아야한다는 점에서 흥미로운 주제입니다. 코드 작성 방법과 새로운 팀원이 팀에 합류하면 코드가 명확하게 문서화되어 있기 때문에 기능과 코드 작동을 이해할 수있는 것보다 처음에 무엇을해야하는지 숙고하는 데 시간을 들일 필요가 없습니다.

따라서 코드는 주석을 잘 달아야하며 외부 문서가 필요없는 자체 문서화 된 코드 여야합니다.

경력에서 나는 다양한 수준의 문서와 품질을 가진 코드를 보았습니다 (문서와 품질은 직교 문제입니다). 품질 향상에 사용되는 문서화에 소요되는 시간을 선호합니다. 간단한 경우를 위해 함수를보고 문서 주석을 생성 할 수있는 GhostDoc과 같은 도구가 있습니다. GhostDoc이 함수의 기능을 나타내는 의미있는 주석을 생성 할 수 있다면 이름이 지정된 함수의 목표를 달성 한 것입니다.

대부분의 경우, GhostDoc은 함수가 실제로 무엇을하는지 말하기조차 시작할 수 없습니다. 이 문제를 해결하고 ghostdoc을 사용하여 코드를 자동 생성하는 시간이 더 좋습니다.

자세한 내용 은 Bob Martin의 Clean Code and PPP 를 참조하십시오 .