코드 문서 먼저? [닫은]

실제로 코드를 작성하기 전에 먼저 완전한 코드 문서를 작성해 본 적이 있습니까? 구체적인 인터페이스를 작성하는 데 도움이되고 클래스의 상호 작용 방식에 대해 생각하게함으로써 초기 디자인이 바닥에 없는지 확인해야한다고 생각했기 때문에 이에 대해 이전에 생각했습니다. 이것이 좋은 생각입니까? 누구든지 그것을 시도 했습니까? 엘

예.

정확히 코드가 무엇을해야하는지 생각하게합니다 . 아이디어는 코드의 어느 부분에서나 시작할 수 있으며 해당 모듈을 완성하기 위해 수행해야 할 작업을 정확히 알고 있다는 것입니다.

또한 IDE에서보다 드로잉 보드에서 무언가를 수정하는 것이 더 쉽습니다.

그것에 대해 생각하는 두 가지 방법이 있습니다.

1) Word 문서, Wiki 등의 문서. 정의에 따라 문서화 할 코드가 없으므로 완전한 코드 문서를 가질 수 없습니다. 고급 설계, 가정, 인터페이스 및 계약을 먼저 문서화 할 수 있습니다.

2) 실행 가능한 테스트 문서. 실행 가능한 단위 테스트가 가장 좋은 문서라고 생각하는 학교가 있습니다. 이 생각의 학교는 또한 코드 (TDD)를 작성하기 전에 이러한 종류의 문서를 옹호합니다. 동시에 전체 시스템에 대한 모든 테스트를 처음부터 작성하지는 않습니다. 먼저 유스 케이스별로 분류 한 다음 유스 케이스 당 테스트 및 코드를 수행합니다.

문서로 시작하는 것은 클래식 폭포 모델이며 해당 모델과 관련된 모든 함정이 있습니다. 일반적으로 문서가 많을수록 요구 사항이 변경 될 때 더 많이 업데이트해야합니다. 사용자 설명서를 시작하면 얻을 수있는 한 가지 이점은 피드백을 빨리받을 수 있다는 것입니다. 그러나 경험에 따르면 대부분의 사람들은 문서를 행동에 정신적으로 매핑하는 데 어려움을 겪고 있습니다. 그래서 우리는 사람들이 실제로 소프트웨어를 사용하고 피드백을 줄 수있는 프로토 타입을 대신 사용합니다.

"문서 우선"의 한 가지 변형은 문맹 프로그래밍 입니다. 프로그래머의 관점에서 프로그램의 기능에 대한 설명을 작성하여 시작하십시오. 컴파일 될 때까지 계속 조정하십시오. 읽기 프로그램 인 Voila

나는 개인적으로 흐름을 보여주기 위해 간단한 모델링을하기 위해 다이어그램 (UML과 같은)을 사용하는 것이 더 낫습니다. 이것은 말로 내용을 문서화하는 것보다 훨씬 빠르며 올바르게 수행하면 설명처럼 될 수 있습니다. 개인적으로 나는 내가 작업 한 프로젝트를 가지고 있지 않았기 때문에 프로그래밍 과정을 통해 변경되지 않았으므로 Full Documentation을 주저 할 것입니다.

편집 : 그러나 오래 갈수록 일부 문서를 작성해야합니다. 이렇게하면 나중에 전체 문서를보다 쉽게 ​​수행 할 수 있습니다.

Joshua Bloch는 "Coders at Work"에 대한 그의 인터뷰에서 바로이 점을 논의합니다.

더 많은 정통 및 학문적 견해와는 달리, 그는 당신의 생각에 맞춰 조정할 것을 조언합니다 (당신이 직접 읽을 수 있을까요?). "느낌. 이를 위해 인터페이스의 일부와 인터페이스를 사용하는 일부 클라이언트 코드를 디자인했습니다.

가장 중요한 것은 무엇을 만들려고하는지, 어떤 문제를 해결하려고하는지 아는 것입니다. 요구 사항 분석의 중요성은 아무리 강조해도 지나치지 않습니다. “아, 그래요 요구 사항 분석; 고객에게 가서 '무엇이 필요합니까?'라고 말합니다. 그는 당신에게 말하고 당신은 끝났습니다.”

더 이상 진실에서 멀어 질 수는 없습니다. 협상 일뿐만 아니라 이해의 과정이기도합니다. 많은 고객들이 문제를 말하지 않을 것입니다. 그들은 당신에게 해결책을 말할 것입니다. 예를 들어 고객은“이 시스템에 다음 17 가지 속성에 대한 지원을 추가해야합니다. 그런 다음 '왜? 시스템으로 무엇을 하시겠습니까? 어떻게 진화 할 것으로 예상합니까? '”등. 모든 고객이 실제로 소프트웨어를 필요로하는 것이 무엇인지 파악할 때까지 앞뒤로 이동합니다. 유스 케이스입니다.

이 단계에서 수행 할 수있는 가장 중요한 작업은 좋은 사용 사례를 제시하는 것입니다. 일단이를 확보하면 가능한 모든 솔루션을 측정 할 수있는 벤치 마크를 갖게됩니다. 합리적으로 가까이 다가가는 데 많은 시간을 할애해도 괜찮습니다. 잘못 이해하면 이미 죽었 기 때문입니다. 나머지 과정은 무용지물이 될 것입니다.

당신이 할 수있는 최악의 일은 (이런 일을 본 것입니다) 6 개월 동안 일할 수있는 똑똑한 사람들을 방으로 데려 가서 그것이 무엇인지 실제로 이해하기 전에 247 페이지 시스템 사양을 작성하는 것입니다. 구축하려고합니다. 6 개월이 지나면 쓸모 없을 수있는 매우 정확하게 지정된 시스템을 갖게됩니다. 그리고 종종 그들은“우리는 그것을 구축해야 할 사양에 너무 많이 투자했습니다.”라고 말합니다. 그래서 그들은 쓸모없는 시스템을 만들고 결코 사용되지 않습니다. 그리고 그것은 끔찍합니다. 유스 케이스가 없다면 무언가를 구축 한 다음 아주 간단한 일을하려고 노력합니다.“오, 세상에, XML 문서를 가져 가서 인쇄하는 것과 같이 매우 간단한 일을하는데 보일러 플레이트 페이지에 페이지가 필요합니다 암호." 그리고 그것은 끔찍한 일입니다.

-Joshua Bloch, Peter Seibel의 " 직업 코더 : 프로그래밍 기술에 대한 고찰 "인터뷰에서

이미 이러한 내용을 고려하고 있다면 책을 들고 인터뷰 내용을 모두 읽어 보는 것이 좋습니다. 내가 말했듯이, 그는 항상 매우 깨달았습니다.

어떤 사람들은 더 나아가서 회사가 완전히 거꾸로 일해야한다고 말합니다.

1. 보도 자료 작성
2. FAQ 작성
3. 고객 경험 정의
4. 사용 설명서 작성
5. 프로그래밍 시작

http://www.allthingsdistributed.com/2006/11/working_backwards.html을 참조 하십시오

완전한 코드 문서를 먼저 작성하는 것은 아마도 과잉 방법이며 폭포 방법론을 다소 연상시킵니다. 그러나 더 실용적인 접근 방식은 README를 먼저 작성하는 것 입니다. 이유는 다음과 같습니다.

README는 프로젝트의 모든 세부 사항을 문서화 하지는 않습니다 . 대신 일반적으로 다음 정보가 포함됩니다.

1. 설명 : 짧은 "판매 피치". 독자들에게 왜 계속 읽어야하는지 알려주십시오.
2. 간단한 예 : 설명을 지원하는 짧은 코드 스 니펫 또는 스크린 샷
3. 빠른 시작 : 시작 하는 방법, 설치 지침 및 기타 예제
4. 추가 문서 : 전체 문서 및 추가 정보에 대한 링크.
5. 프로젝트 구성 : 저자, 기여 방법, 버그 신고 방법
6. 법적 고지 : 라이센스, 저작권 및 기타 법적 세부 사항.

"판매 피치"를 미리 작성하면이 프로젝트가 존재하는 이유와 개발자가 사용해야하는 이유를 명확하게 알 수 있습니다. 프로젝트를 설명하기 위해 전체 문장을 작성하는 단순한 행동은 종종 프로젝트를 더 잘 바꿉니다. 프로젝트를 더 잘 이해하고 새로운 아이디어를 개발하며 잠재적 인 문제를 발견합니다. 또한 "우수 판매"에 포함 된 모든 항목은 필수 항목입니다!

"빠른 예"와 "빠른 시작 안내서"를 통해 사용자 관점에서 핵심 사용 사례를 생각해보아야합니다. 구현 세부 사항과 마감 기한이 지체되기 전에 코드를 작성하기 전에이 작업을 수행하면 API와 디자인이 훨씬 깨끗해집니다. 기억하십시오 : 사람들이 읽을 수 있도록, 프로그램은 우연히 실행되도록 프로그램을 작성해야합니다 ( SICP ).

"추가 문서"에서는 나중에 수행하기 위해 자세한 문서가 필요한 부분의 개요를 작성합니다. "프로젝트 구성"을 통해 프로젝트를 수행 할 사람과 코딩 방법을 파악할 수 있습니다. "법적 고지"... 글쎄, 그것들도 방해가 될 수 있습니다.

이 기본 README를 설치 한 후에는 토론, 디자인 검토, 작업 분할 및 프로젝트 계획에 유용한 문서가 제공됩니다. 프로젝트 작업을 진행할 때 README를 자주 확인하여 여전히 제대로 진행되고 있는지 확인하십시오. 또한 README와 "추가 문서"를 증분 업데이트하면 코드 작성이 완료되면 모든 문서가 작성되므로 마지막 순간에 모든 것을 문서화하는 것보다 훨씬 즐거운 경험입니다.

자세한 내용은 다음을 확인하십시오.

1. 읽어보기 중심 개발
2. 가장 중요한 코드는 코드가 아닙니다
3. 당신은 당신이 문서입니다

왜 수업이 상호 작용하는지에 대해 생각하고 싶지 않습니까? 왜 나쁜 일입니까? 나는 수업이 무엇인지 알기 전에 실제로 상호 작용에 대해 생각합니다. 그런 식으로 수업은 스스로를 식별합니다.

코드를 작성하기 전에 수행 할 작업에 대한 아이디어가 있어야합니다. 문제는 항상 코딩 한 내용과 작성한 내용을 어떻게 동기화 하는가입니다. 어떤 사람들은 시도하지 않는다고 말하고 다른 사람들은 초기 문서를 잊고 의견을 유지한다고 말합니다. 물론 코드는 항상 표준 소스입니다. 문제는 나중에 코드를 사용하거나 나중에 사용하는 사람들을 위해 코드의 기능을 문서화하려는 노력이 가치가 있는지 여부입니다. 누구나 기능이 무엇을하는지 알아낼 수 있습니다. 작가의 임무는 누군가가 한 시간 안에 누구나 알아낼 수있는 것을 5 분 안에 이해하도록 돕는 것입니다. 델타를 추가하고 경로를 결정하십시오.