9/29일 전자신문 세미나 자료

1. 프레임워크 문서화 잘하기 (Patterns for Effectively Documenting Frameworks)EVA 박선욱한국예탁결제원서강대학교 SE랩

2. 목차GoalWhat is FrameworksWhy Documenting Frameworks? What is The Good Framework Documentation?Introduce PatternsReference

3. Offical Goal객체지향 프레임워크의 효과적인 문서화. (비전문가를 위한)

4. Personal Goal프레임워크가 무엇인지 정확히 알기어떤 프레임워크든 빠르게 습득하기

5. What is FrameworksDouglas C. Schmidt Says..Frameworks define “semi-complete” applicationthat embody domain-specific object structures and functionality.+to produce custom application

6. Libraries is..Application BlockDATABASEADTsMATHNETWORKINGApp SpecificLogicOO DesignInvocationsGRAPHICSGUIEventLoopSingletonStrategySelectionsReactorAdapterStateActive ObjectDesign PatternClass Library Component Architecture

7. But Framework is ..Control – Flow (IoC)Active ObjectStateNETWORKINGGUIMATHReactorEventLoopApp SpecificLogicInvocationsCallbacksADTsSingletonAdapterDATABASEGRAPHICSApplication FrameworkComponent Architecture

8. Why Documenting Frameworks?

9. Frameworks help us …설계와 코드의 재사용을 통한생산성 향상빠른 개발호환성과 일관성의 향상

10. Software reuse상세한 소스코드부터 추상화된 아키텍처까지프레임워크는 중간에 위치하는 강력한 재사용 기술이다.Components (소스) + Patterns Technology (설계)

11. But …No Pain! No Gain!For reuseGood design and implementationAnd … ??

12. Why Documenting Frameworks?프레임워크는 확장성과 유연성을 가져야 한다.이 부분은 본질적으로 어렵다.

13. Why Documenting Frameworks?학습곡선은 좋은 문서로 단축시킬 수 있습니다.

14. Framework based developmentApplicationrefiningapplyingdesigning andimplementingFrameworkDomainunderstandingapplication developerevolvingunderstandingDocumentationframework developerdocumenting

15. What is The Good Framework Documentation?

16. What is The Good Technical DocumentationThe book “Developing Quality Technical Information”

17. Key Issues of Framework Documentation내용측면Usage and Design 정보의 조화Contents의 구조Contents의 표현다양한 경로 제공관리측면일관성과 중복다양한 표현방법Contents의 통합

18. Usage vs Design Information좋은 제품은 내부 구조를 알지 못해도 사용할 수 있어야 한다. 대부분의 프레임워크 문서들은 내부 설계와 아키텍처 설명에 집중되어 있다. But frameworks documentation must mix.

19. What is The Good Framework Documentation?Reader’s point of view :task-oriented informationwell organizedunderstandableeasy to retrieveWriter’s point of view : identifying the documentation needsselecting the contentschoosing the best representationorganizing the contents adequately

20. Pattern LanguagesDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide

21. This pattern language give us 가이드 라인이 되어준다. 효과적이다. 재사용을 지원한다.

22. Pattern Application: A Typical Sequence

23. Framework OverviewDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference GuidePattern : Framework Overview

24. What is the Framework Overview

25. Problem프레임워크의 첫인상을 어떻게 하면 빠르고 정확하게 알려줄 수 있을까? 즉, 해당 프레임워크가 할 수 있는 것이 무엇인지 짧고도 정확하게 알려줄 수 있을까?Pattern : Framework Overview

26. Forces다양한 독자들특히, 프레임워크 선별자완전성정보를 충분히 제공해야 한다.그런데, 문제는 독자 별로 ‘충분히’가 다르다.쉬운 이해ClarityvsCompleteness예제는 이해를 돕는데 탁월한 수단이다.

27. Different audiences애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수자다른 프레임워크 개발자

28. Solution프레임워크의 커버리지를 명시고정(불가능한 영역)유연(가능한 영역)프레임워크의 도메인 용어를 구축프레임워크 선별자를 주 독자로 작성Pattern : Framework Overview

29. Example (JUnit)Pattern : Framework Overview

30. Pattern : Framework OverviewExample (Spring)

31. Pattern : Graded ExamplesDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference GuidePattern : Graded Examples

32. Problem어떻게 독자가 자신의 애플리케이션에 해당 프레임워크 적용이가능한지 알 수 있도록 도와 줄까?문인은 붓로말하고 무인은 칼로 말한다. 하지만개발자들은 코드로 말한다.Pattern : Graded Examples

33. ForcesTask 중심무엇을 할 수 있고, 어떻게 하면 되나다양한 독자들비용(Cost)대비 효율TDD를 한다면, 별도의 예제를 따로 만들지 않아도 된다.

34. Solution예제를 단계적으로 제공좋은 예제 집합도메인 용어로 구성프레임워크 기능들의 표현다른 문서화를 완성시키는 역할예제는추상화된 설계보다 이해하기 쉽다프레임워크의 유용성을 바로 알 수 있게 해준다프레임워크의 유용성 뿐만 아니라 제한성도 보여 준다. 프레임워크의 설계가 아닌 사용법을 보여준다.Pattern : Graded Examples

35. Example (JUnit)Pattern : Graded Examples

36. Example (Spring)Pattern : Graded Examples

37. Pattern : Documentation RoadmapDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide

38. What is the Documentation Roadmap

39. Problem어떻게 하면 독자가 필요로 하는 정보를 쉽게 찾을 수 있도록 도와 줄 수 있을까?Pattern : Documentation Roadmap

40. Forces다양한 독자들애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수인다른 프레임워크 개발자각기 다른 재사용찾는 방법의 난이도Pattern : Documentation Roadmap

41. SolutionTask 중심산발적 읽기도 지원navigating top-down from a main entry point navigating bottom-up from a small piece of information.전체적인 조정 가능성을 향상시켜라관련된(독자/기능/사용순서) 주제끼리 묶어라 탭과 번호, 단락 등을 이용하여 보기 좋게 하라Pattern : Documentation Roadmap

42. Example (JUnit)Pattern : Documentation Roadmap

43. Example (Spring)Pattern : Documentation Roadmap

44. Pattern : Cookbook & RecipesDocumentation Roadmap Framework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference GuidePattern : Cookbook and Recipes

45. What is Cookbok & Recipes

46. Problem어떻게 하면 독자가 빠르게 프레임워크를 사용 할 수 있게 해줄 수 있을까?Pattern : Cookbook and Recipes

47. ForceTask 중심사용방법과 설계정보 사이의 균형다양한 독자들초보자고수완전성바로 적용할 수 있는 난이도비용대비 효과

48. SolutionCookbook레시피들을나선형 구조로 나열“Framework overview” is often the first recipe레시피의 구성목적절차예제Pattern : Cookbook and Recipes

49. Example (JUnit)Pattern : Cookbook and Recipes

50. ExamplePattern : Cookbook and Recipes

51. Pattern : Customizable PointsDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide

52. What is Customizable PointHot-spot 커스터마이제이션은사전에 정의된 개선영역에 의해서 수행된다.Hook변경되어야 하는 영역과 방법 : 따라야 하는 제약사항과 Hook의 영향Hot spot은 하나 이상의 Hook으로 구성Pattern : Customizable Points

53. Hot-spot ModelWhite Box Black BoxPattern : Customizable Points

54. Problem독자에게 프레임워크에서 커스터마이징 가능한 부분을 알려주려면 어떻게 해야 할까? 그 부분들의커스터마이징하는 방법을 알려주려면 어떻게 해야 할까?Pattern : Customizable Points

55. ForceTask 중심사용법과 설계정보 사이의 균형다양한 독자완전성문서에 대한 쉬운 이해

56. Solution별도로 커스터마이징 가능한 부분들의 목차를 제공기능별부분이나 모듈별잘 사용되지 않음사용법은 “Cookbook & Recipes”과 중복설계정보는 “Design internals”과 중복Pattern : Customizable Points

57. Example (Junit)Pattern : Customizable Points

58. Pattern : Design InternalsDocumentation Roadmap Framework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide

59. Problem진보된 커스터마징을 원하는 독자에게 어떻게 프레임워크의 설계와 구현에 대해서 알려줄 수 있을까?Pattern : Design Internals

60. Force다른 목적들사용법과 설계정보 사이의 균형설계정보 복잡성의 최소화Pattern : Design Internals

61. Solution정확하고 상세한 프레임워크의 내부 설계정보를 제공especially hot-spots. can help them better understand and enable more advanced customizations 아키텍처와 설계원칙디자인 패턴을 이용간단한 표현풍부한 정보 제공Pattern : Design Internals

62. Example (JUnit)Pattern : Design Internals

63. Review : Pattern LanguagesDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide

64. Reference“Patterns for Effectively Documenting Frameworks” –Ademar Aguiar and Gabriel David“질서 있는 아키텍처 패턴이야기” – 김용현(마이크로소프트웨어)“Framework Engineering” – 손영수(www.arload.net)www.junit.orgwww.springsource.orgwww.google.comwww.evacast.net

65. Q & A