얼마나 많은 문서가 충분합니까?

얼마나 많은 기술 문서 (미래의 개발자를위한)입니다 충분 ? 코딩 시간과 기록 시간 사이에 적절한 비율이 있습니까?

Papadimoulis는 당신이해야 한다고 주장

이해를 돕기 위해 필요한 최소한의 문서를 작성합니다.

이것이 좋은 지침입니까, ​​아니면 제가 만들어야 할 특정 사항이 있습니까?

복도 유용성 테스트는 어떻습니까? 프로젝트에 익숙하지 않은 개발자에게 코드와 문서를 보여주십시오. 코드를 검토하는 동안 무언가를 설명하려는 압도적 인 충동없이 그렇게 할 수 있다면 충분합니다.

완벽 함과 동시에 비싸지 않은 쿼터, 더하기 rien a ajouter, mais quand il n'y a plus rien à reretirer.
앙투안 드 생 텍쥐페리

나는이 주제에 대해 잠시 생각하고 있었다.

내 결론은-양의 문제가 아니라 품질과 맥락의 문제입니다.

예를 들어, 적절한 프로젝트 구조는 파일이있는 위치를 설명하는 주석보다 우수합니다 (구현 대 강렬)

이와 유사하게, 문맥을 명확하게하기위한 분류는 이름 지정에 영향을 미칩니다 (환자의 ID-> 환자 .ID).

나는 DDD가 좋은 문서를 가지고 있다고 생각합니다. 분류는 컨텍스트를 제공하고 컨텍스트는 경계를 만들고 경계는 의도적 인 구현으로 이어집니다 (이것이 존재하는 것이 아니라 그것이 속한 곳입니다).

코드 자체는 문서로 간주하기에 충분하지 않습니다. 대부분의 경우 문제는 코드의 작동이 주석 처리되거나 주석 처리되지 않고 오히려 구동력 (도메인 논리)이 아니라는 사실에 있습니다.

코드가 변경되면 도메인 논리 또는 추론이 수행되지 않아야하지만 도메인 논리 또는 추론이 변경되면 코드가 확실히 변경됩니다.

일관성도 매우 중요합니다. 일관성이 없으면 규칙 자체는 쓸모가 없습니다.

디자인 패턴은 단지 '좋은 습관'이 아니라 개발자들이 이해해야 할 용어입니다. 개발자에게 팩토리에 새 유형을 추가하도록 지시하는 것은 메소드에 새 유형을 추가하는 것 (컨텍스트 및 일관성이 약하거나없는)보다 더 잘 이해됩니다.

투쟁의 절반은 친숙 합니다.

참고로 많은 문서를 선호하는 API는 도메인과 상황에 따라 매우 중요합니다. 때때로 복제 기능은 악하지 않고 (같은 것, 다른 상황) 별도의 것으로 취급해야합니다.

논평의 관점에서, 추론의 배후에있는 도메인 논리를 지적하는 것이 좋습니다.

예를 들어 의료 산업에서 일하고 있습니다. 당신의 방법에서 당신은 "IsPatientSecure = true;"

이제 괜찮은 프로그래머라면 환자가 안전한 것으로 표시되고 있음을 알 수 있습니다. 그런데 왜? 의미는 무엇입니까?

이 경우 환자는 구내 병원으로 안전하게 이송 된 수감자입니다. 이것을 알면,이 시점까지 이어지는 사건들 (그리고 아마도 여전히 필요한 일)을 상상하기가 더 쉽습니다.

어쩌면이 게시물은 가장 철학적으로 보일 수도 있지만 코드가 아니라 작성하는 것이 "추론 적"이거나 "논리적"이라는 것을 기억하십시오.

나는 Papadimouslis 인용에 동의합니다. 소스 코드는 그 자체로 말할 수는 있지만 코드가 존재하는 이유, 사용 방법 및 코드 작동 방식을 알려줄 수는 없습니다.

나는 좋은 비율을 모른다.

문서가 거의없이 수백 줄의 코드를 물려 받았습니다. 코드가 작성된 이유를 이해하기가 어려워졌습니다. 코드가 작성된 이유를 찾은 후 코드 사용법을 알아 내야했습니다. 그 사실을 알게 된 후에는 코드를 지원하고 유지할 수 있도록 어떻게 행동해야하는지 이해해야했습니다.

경험을 바탕으로 주석을 너무 구체적으로 작성하지 마십시오. 그렇지 않으면 실제 코드와 문서를 유지해야합니다. 문서와 코드가 동기화되지 않은 것은 악몽입니다.

두 번째로 자신을 추측하는 것을 멈출 수 있습니다.

만약 당신이 일하는 동안 언제라도 "음, 내가 이것을 문서화해야 할 것 같다"라면, 계속해서 그것을하십시오. 그런 다음 문서를 작성했는데 "이것을 더 설명해야 할 수도 있습니다"와 같은 경우 계속 진행하십시오.

그 느낌 이 사라질 때까지 반복하십시오 .

George Fairbanks의 저스트 엔포 프 소프트웨어 아키텍처 (Just Enough Software Architecture)에 제시된 것과 같은 위험 중심 접근 방식이 문서의 양을 충분히 이해하는 데 매우 효과적이라는 것을 알았습니다. 그의 웹 사이트에서이 개념 (3 장)을 보여주는 섹션을 읽을 수 있지만 주요 아이디어는 다음과 같습니다.

• "시스템 이해"에 대해 걱정하는 것을 위험으로 표현하십시오.
• 위험의 우선 순위
• 팀이 프로젝트 위험이 충분히 줄었다 고 느낄 때까지 위험을 완화하십시오. 이 경우 아마도 일종의 문서를 작성하게 될 것입니다.

우려 사항을 보정하여 위험의 우선 순위를 정할 수 있도록 성공 임계 값 이라고 알려진 몇 가지 목표를 파악하는 것이 도움이되었으므로 팀이 "성공적인"프로젝트가 달성해야한다고 생각하는 최소 목표입니다. 문서 관점에서 ToS의 예는 "개발자가 처음으로 프레임 워크를 선택한 후 4 시간 내에 간단한 플러그인을 빌드 할 수 있어야합니다"와 같은 것일 수 있습니다.

이제 몇 가지 위험을 식별하십시오. 시스템을 구축 (또는 구축)하면서 팀이 가장 걱정하는 것은 무엇입니까? 이것을 위험 진술로 표현하십시오. 나는 SEI의 조건-결과 스타일을 좋아하지만 다른 것들도 있습니다. 예 :

• 데이터 모델은 크고 복잡합니다. 개발자는 주어진 상황에서 어떤 데이터 요소를 사용할지 모를 수 있습니다.
• 시스템에는 안정성을 높이기 위해 API 연결 제한이 있습니다. 개발자가 실수로 연결 제한을 넘어 설 수 있습니다.
• 플러그인은 몇 가지 순차적 단계로 소비됩니다. 개발자는이 순서 단계를 염두에두고 플러그인을 빌드하지 않을 수 있습니다.

이제 팀으로서 위험의 우선 순위를 정하십시오. 멀티 투표는 매우 효과적입니다.

우선 순위가 가장 높은 위험을 완화하고 프로젝트 실패 위험 (성공 임계 값으로 정의)이 허용 가능한 한계 내에있을 때까지 식별을 시작하여 반복하십시오. 일반적으로 이는 팀이 동의하지 않을 위험이 있다는 것을 의미합니다. 모든 위험을 완화하고 싶지는 않을 것입니다. 위의 마지막 위험에 대한 완화 전략의 예는 자습서를 만드는 것입니다.

가능한 적은, 그러나 필요한만큼

처음 어디서 들었는지 언제 기억이 나지 않지만 많은 응용 프로그램에서 최대입니다.

기술이나 응용 프로그램이 복잡할수록 더 많은 문서가 필요하지만 (선명하게) 더 많은 시간을 낭비하고 싶지는 않습니다.

JohnFx의 '홀 웨이 테스트'는 건전합니다. 그러나 자신을 믿으십시오. 코드를 개발 했으므로 모든 사람들의주의를 기울여야 할 요소와 모두에게 분명한 요소를 고려해야합니다. 코드를 개발하는 데 따른 어려움을 생각해 보면 다른 개발자가 코드를 볼 때 무엇을 보게 될지 알 수있을 것입니다.

코딩 노력과 문서화 노력 사이의 관계를 잊어 버리십시오.

나는 당신이 이것을 정확한 규칙에 넣을 수 없다고 생각합니다. 문서화의 이유는 원시 코드에서 쉽게 수집되지 않은 지식을 양식으로 제공하여 다른 사람들이 원시 코드를 이해하고 유지 보수 할 수 있도록하기위한 것입니다.

따라서 충분히 문서화되었는지 알 수있는 유일한 방법은 대상 사용자에게 충분한 지 물어 보는 것입니다. "피어 리뷰"프로세스가이 작업을 매우 잘 수행한다고 생각합니다. 동료가 당신이 말하는 것을 이해하고 그것을 최소화하기 위해 얼마나 많은 설명이 필요한지 주목하십시오.

이전에이 작업을 수행 한 적이 없다면 얼마나 많은 작업을 수행 할 것인지 예측할 수 없지만 몇 번의 반복 후에는 얼마나 많은 작업이 필요한지 더 잘 알 수 있습니다.