건축 설계 문서화 전략

Question

현재 단계까지 소프트웨어 프로젝트를 문서화하려고합니다. 독자층은 나 자신 (미래의 시간에), 다른 개발자 (현재 및 단기적인 미래) 및 최종 사용자를 포함합니다. 따라서 문서에는 설계 요구 사항, 아키텍처/디자인 (데이터 구조, 아키텍처, 사용자 인터페이스, 절차 설계), 기술 문서 및 최종 사용자 지침에 대한 설명이 있습니다. 문서는 주로 역사적인 기록을 제공하기 위해 제작되었습니다. 현재이 프로젝트에 참여한 2 명의 팀으로 구성되어 있지만 다른 사람들의 프로젝트에서 더 많은 기능이 추가되어 단기간에 더 많은 사람들이 참여할 수 있습니다.

내가 겪고있는 것은 건축 설계 문서 (http://en.wikipedia.org/wiki/Design_document)입니다. doxygen을 사용하여 몇 가지 유형의 데이터 흐름 다이어그램을 만들려고했지만 쉽지 않았습니다. C++ 코드에서 데이터 흐름 다이어그램을 쉽게 생성 할 수있는 도구가 있습니까? 아니면 Microsoft Visio에서 수동으로 그리는 경우입니까? 미리 감사드립니다.

Answer 1

소스 코드에서 자동으로 생성 된 모든 하위 레벨 다이어그램은 쓸모가 없습니다. 그들은 일 것입니다.은 코드보다 불분명하고 지저분한 시각적 레이아웃을 가지며 곧 변경 될 수 있습니다. 미래의 개발자들은 코드를 불신하고 대신 코드를 보게되므로 소스 코드를 리팩터링하는 데 더 많은 노력을 기울일 수 있습니다 (즉, 설명이 가능한 이름을 사용하고, 문제 도메인을 명확하게 나타내는 클래스 구조를 유지해야합니다. 에).

좋은 javadoc 또는 doxygen 주석을 작성하여 최신 상태로 유지하는 것이 좋습니다. 많은 사람들이이를 매우 유용하다고 생각합니다.

상위 수준 다이어그램도 유용합니다. Martin Fowler의 UML Distilled을 읽고 UML 표기법을 익히십시오. 그런 다음 Viso 또는 다른 그래픽 편집기를 사용하여 향후 개발자에게 도움이 될만한 소프트웨어 부분 만 문서화하십시오. 다이어그램을 "완벽하게"완벽하게 만드는 데 시간을 낭비하지 마십시오. 다른 개발자에게 가장 도움이되는 것에 집중하십시오.

Answer 2

건축가 에디션 구성 요소가 포함 된 Visual Studio Team Suite 평가판을 다운로드 할 수 있습니다.

Answer 3

도구가 코드를 문서화하려면 먼저 코드를 읽어야합니다.

코드를 읽는 것을 "리버스 엔지니어링"이라고도합니다.

코드는 다양한 도구로 리버스 엔지니어링 할 수 있으며, 그런 다음 해당 코드의 UML 다이어그램을 만들 수 있습니다. 안타깝게도이 작업을 몇 년 전에 시도해 보았을 때 리버스 엔지니어링 C#에서 훌륭한 작업을 수행하는 일부 도구 (예 : 리버스 엔지니어링 C++)가 불완전한 작업을 수행한다는 것을 알았습니다 (C++은 구문 분석하기가 더 어려우므로 비 -OO 전역 기능 등).

"역 공학"또는 "왕복"이라는 용어와 함께 "C++", "UML"또는 "diagram"과 함께 Google을 사용하면 많은 도구를 찾을 수 있습니다.

Microsoft는 향상된 C++ 도구를 약속했지만 그 일정이 무엇인지 알 수 없습니다.