원본 자체 내에 소스 코드에 대한 디자인 문서를 작성할 수 없습니까? 나는 Doxygen과 같다고 생각하지만 초점은 구현에서 설계로 옮겨 갔다. 근본적으로 (그리고 오히려 흥미롭게도) 여러분은 소스 파일의 끝에 markdown이라는 멋진 큰 덩어리를 가지고 있습니다.코드 원본에 디자인 문서를 포함시키지 않는 이유가 있습니까?
새로운 소스 파일을 만들 때마다 (그리고 선명한 화이트 페이지로 글쓰기 시작할 때마다) 나는 거기에 쓰여진 첫 번째 내용이 메모, 생각 및 아이디어라면 좋을 것이라고 생각합니다. 모듈이 달성하기를 희망/필요/꿈꾸던 것의 탐구. 아마도 소스 코드와의 근접성 때문에 문서화에 대한 관심이 더욱 높아질 것입니다.
어쩌면 내가 자기 기록 코드 작성에 시간을 할애해야 할 수도 있습니다.
소스 코드에 디자인을 포함 할 때의 한 가지 문제점은 소스 레이아웃/구조가 파일 수준에서 문서화하기에는 너무 세분화되어있어 좋고 깨끗한 자체 문서화 코드를 작성하는 것입니다. 리팩토링 너트 인 경우 많은 작은 파일이있을 수 있으며 각 파일을 문서화하는 것은 무의미합니다 (모든 노트를 읽는 것은 매우 어려움).
네임 스페이스/모듈/구성 요소 수준에서 좀 더 일반적인 디자인 노트 (readme)를 사용하면 정말 유용 할 수 있습니다. "내가 처음 알게되면 무엇을 알고 싶습니까?" , 일반 영어로 작성, 공개 질문, 의사 결정 등 분명히 아래로 지적했다.
내가 많이하는 점은 먼저 빈 메소드 스텁을 작성하고 기술 설계를 주석으로 넣고 한 줄에 개개인을 작성하는 것입니다. 그런 다음 각 주석 행 뒤에 디자인이 말하는 코드를 작성합니다.
Donald Knuth가 발명 한 Literate Programming이라고 할 수 있습니다. 자체 문서화 코드에 관해서는, 내가 말할 수있는 것은 내가 본 적이 없다는 것입니다.
누가 우리가하지 않는다고 말합니까?
문서 XML 또는 Doxygen 문서 주석 (예 : 클래스)은 클래스 작동 방식을 설명하는 데 이상적인 곳입니다.
역사적으로 임베디드 문서 (소스 파일에 저장 됨)의 가장 큰 문제점은 텍스트 기반이어야하며 특히 스크린 샷과 다이어그램이 필요한 곳에서 쓰기 및 읽기가 어려워야한다는 것입니다. 그러나 Visual Studio 2010을 사용하면 추가 정보를 소스 코드 파일 (비트 맵 이미지 등)에 쉽게 포함 할 수 있으므로 wysiwyg 설명서를 코드에 직접 포함시킬 수있는 몇 가지 확장 기능이 곧 나타납니다.
한편, 스크린 샷과 다이어그램이 필요한 복잡한 문서의 경우 코드와 함께 '문서'폴더에 문서를 저장하기 만합니다. 따라서 어셈블리를 사용하려는 경우 어셈블리의 개요/디자인은 다음과 같습니다. 코드 바로 옆에있는 버전 관리 된 문서에 의해 제공됩니다. 이것은 소스 코드에 포함되어 있지는 않지만 필요할 때 손에 항상 가깝습니다.
개인적으로 나는 편집자의 열렬한 팬이 아니다. 나는 내가 상대방과 협력 할 때 거의 생각하지 않기 때문에 문서와 그 내용의 분리가 분리 가능해야한다고 생각한다. IDE가 비트 맵을 소스 코드에 임베딩 할 수있는 기능을 제공한다는 사실에 약간의 공감을 나타 냈습니다 :) ... Microsoft 제품이 아닌 다른 제품에서 이러한 파일을 열면 어떻게됩니까? 그렇지만 문서를 저장소의 별도 디렉토리에 임베드하는 것은 기능면에서 소스 코드 자체에있는 것과 동일합니다. –
'WYSIWYG'문서는 단순한 텍스트 스타일 이상입니다. 다이어그램과 그림은 종종 중요한 .doc 파일을 사용하는 경우가 많습니다. VS2010은 이러한 종류의 외부 '메타 데이터'코드를 인라인으로 렌더링하는 * 기능 *을 갖추고 있습니다. 잘 사용된다면 문서는 소스 코드 * display *에 매우 유용하게 포함될 수 있습니다. 이것이 소스 코드에 저장되어야 함을 의미하지는 않습니다. (해체와 그 소스 코드를 혼합하는 것과 유사한 개념 - 때때로 매우 유용한 시각화) –