patterns for effectviely documenting frameworks

65
프프프프프 프프프 프프프 (Patterns for Effectively Documenting Frameworks) EVA 프프프 프프프프프프프 프프프프프 SE 프

Upload: sunuk-park

Post on 14-Nov-2014

15.436 views

Category:

Technology


4 download

DESCRIPTION

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

TRANSCRIPT

Page 1: Patterns for effectviely documenting frameworks

프레임워크 문서화 잘하기 (Patterns for Effectively Documenting Frameworks)

EVA 박선욱한국예탁결제원

서강대학교 SE 랩

Page 2: Patterns for effectviely documenting frameworks

2

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

Page 3: Patterns for effectviely documenting frameworks

3

Offical Goal

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

Page 4: Patterns for effectviely documenting frameworks

4

Personal Goal

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

Page 5: Patterns for effectviely documenting frameworks

What is FrameworksDouglas C. Schmidt Says..

Frameworks define “semi-complete” applicationthat embody domain-specific object structures and functionality.

to produce custom application

+

Page 6: Patterns for effectviely documenting frameworks

Class Library Component Architecture

App SpecificLogic

OO Design

EventLoop

DATABASE ADTs

MATH NETWORKING

GRAPHICS GUI

Singleton Strategy

Reactor Adapter

State Active Object

Invocations

Selections

Application Block

Design Pattern

Libraries is..

Page 7: Patterns for effectviely documenting frameworks

DATABASE

Singleton

GRAPHICS

Adapter

EventLoop

Reactor

NETWORKING

Active Object

GUI

State

App SpecificLogic

MATH

ADTs

Callbacks

Invocations

Application FrameworkComponent Architecture

Control – Flow (IoC)

But Framework is ..

Page 8: Patterns for effectviely documenting frameworks

8

Why Documenting Frameworks?

Page 9: Patterns for effectviely documenting frameworks

Frameworks help us …

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

Page 10: Patterns for effectviely documenting frameworks

10

Software reuse

상세한 소스코드부터 추상화된 아키텍처까지프레임워크는 중간에 위치하는 강력한 재사용 기술이다 .

Components ( 소스 ) + Patterns Technology (설계 )

Page 11: Patterns for effectviely documenting frameworks

11

But …

No Pain! No Gain!For reuse

Good design and implementationAnd … ??

Page 12: Patterns for effectviely documenting frameworks

12

Why Documenting Frameworks?

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

Page 13: Patterns for effectviely documenting frameworks

13

Why Documenting Frameworks?

학습곡선은 좋은 문서로 단축시킬 수 있습니다 .

Page 14: Patterns for effectviely documenting frameworks

14

Framework based development

Documenta-tion

Application

FrameworkDomain

designing andimplementing

evolving

documenting

understanding

understanding

applying

refining

framework developer

application developer

Page 15: Patterns for effectviely documenting frameworks

15

What is The Good Framework Doc-umentation?

Page 16: Patterns for effectviely documenting frameworks

16

What is The Good Technical Docu-mentation

Use

FindUnderstand

Task Orientation

Accuracy

Completeness

Organization

Retrievability

Visual Effectiveness

Clarity

Concreteness

Style

The book “Developing Quality Technical Infor-mation”

Page 17: Patterns for effectviely documenting frameworks

17

Key Issues of Framework Documen-tation

내용측면Usage and Design 정보의 조화Contents 의 구조Contents 의 표현다양한 경로 제공

관리측면일관성과 중복다양한 표현방법Contents 의 통합

Page 18: Patterns for effectviely documenting frameworks

18

Usage vs Design Information

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

But frameworks documentation must mix.

Page 19: Patterns for effectviely documenting frameworks

19

What is The Good Framework Doc-umentation?

Reader’s point of view :task-oriented informationwell organizedunderstandableeasy to retrieve

Writer’s point of view : identifying the documentation needsselecting the contentschoosing the best representationorganizing the contents adequately

Page 20: Patterns for effectviely documenting frameworks

20

Pattern LanguagesDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Page 21: Patterns for effectviely documenting frameworks

21

This pattern language give us

가이드 라인이 되어준다 . 효과적이다 . 재사용을 지원한다 .

Page 22: Patterns for effectviely documenting frameworks

22

Pattern Application: A Typical Se-quence

FRAMEWROK OVER-

VIEW

GRADED EXAMPLES

DOCUME-NATION

ROADMAP

COOKBOOK & RECIPES

CUSTMIZ-ABLE

POINTS

DESIGN IN-TERNAL

Page 23: Patterns for effectviely documenting frameworks

23

Framework OverviewDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Pattern : Framework Overview

Page 24: Patterns for effectviely documenting frameworks

24

What is the Framework Overview

Page 25: Patterns for effectviely documenting frameworks

25

Problem

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

Pattern : Framework Overview

Page 26: Patterns for effectviely documenting frameworks

26

Forces

다양한 독자들특히 , 프레임워크 선별자

완전성정보를 충분히 제공해야 한다 .그런데 , 문제는 독자 별로 ‘충분히’가 다르다 .

쉬운 이해 Clarity vs Completeness예제는 이해를 돕는데 탁월한 수단이다 .

Page 27: Patterns for effectviely documenting frameworks

27

Different audiences

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

Page 28: Patterns for effectviely documenting frameworks

28

Solution

프레임워크의 커버리지를 명시고정 ( 불가능한 영역 )유연 ( 가능한 영역 )

프레임워크의 도메인 용어를 구축프레임워크 선별자를 주 독자로 작성

Pattern : Framework Overview

Page 29: Patterns for effectviely documenting frameworks

29

Example (JUnit)

Pattern : Framework Overview

Page 30: Patterns for effectviely documenting frameworks

30Pattern : Framework Overview

Example (Spring)

Page 31: Patterns for effectviely documenting frameworks

31

Pattern : Graded ExamplesDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Pattern : Graded Examples

Page 32: Patterns for effectviely documenting frameworks

32

Problem

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

Pattern : Graded Examples

Page 33: Patterns for effectviely documenting frameworks

33

Forces

Task 중심무엇을 할 수 있고 , 어떻게 하면 되나

다양한 독자들비용 (Cost) 대비 효율

TDD 를 한다면 , 별도의 예제를 따로 만들지 않아도 된다 .

Page 34: Patterns for effectviely documenting frameworks

34

Solution

예제를 단계적으로 제공좋은 예제 집합

도메인 용어로 구성프레임워크 기능들의 표현다른 문서화를 완성시키는 역할

예제는추상화된 설계보다 이해하기 쉽다프레임워크의 유용성을 바로 알 수 있게 해준다프레임워크의 유용성 뿐만 아니라 제한성도 보여 준다 . 프레임워크의 설계가 아닌 사용법을 보여준다 .

Pattern : Graded Examples

Page 35: Patterns for effectviely documenting frameworks

35

Example (JUnit)

Pattern : Graded Examples

Page 36: Patterns for effectviely documenting frameworks

36

Example (Spring)

Pattern : Graded Examples

Page 37: Patterns for effectviely documenting frameworks

37

Pattern : Documentation RoadmapDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Page 38: Patterns for effectviely documenting frameworks

38

What is the Documentation Roadmap

Page 39: Patterns for effectviely documenting frameworks

39

Problem

어떻게 하면 독자가 필요로 하는 정보를 쉽게 찾을 수 있도록 도와 줄 수 있을까 ?

Pattern : Documentation Roadmap

Page 40: Patterns for effectviely documenting frameworks

40

Forces

다양한 독자들애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수인다른 프레임워크 개발자

각기 다른 재사용찾는 방법의 난이도

Pattern : Documentation Roadmap

Page 41: Patterns for effectviely documenting frameworks

41

Solution

Task 중심산발적 읽기도 지원

navigating top-down from a main entry point navigating bottom-up from a small piece of infor-mation.

전체적인 조정 가능성을 향상시켜라관련된 ( 독자 / 기능 / 사용순서 ) 주제끼리 묶어라 탭과 번호 , 단락 등을 이용하여 보기 좋게 하라

Pattern : Documentation Roadmap

Page 42: Patterns for effectviely documenting frameworks

42

Example (JUnit)

Pattern : Documentation Roadmap

Page 43: Patterns for effectviely documenting frameworks

43

Example (Spring)

Pattern : Documentation Roadmap

Page 44: Patterns for effectviely documenting frameworks

44

Pattern : Cookbook & RecipesDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Pattern : Cookbook and Recipes

Page 45: Patterns for effectviely documenting frameworks

45

What is Cookbok & Recipes

Page 46: Patterns for effectviely documenting frameworks

46

Problem

어떻게 하면 독자가 빠르게 프레임워크를 사용 할 수 있게 해줄 수 있을까 ?

Pattern : Cookbook and Recipes

Page 47: Patterns for effectviely documenting frameworks

47

Force

Task 중심 사용방법과 설계정보 사이의 균형다양한 독자들

초보자고수

완전성바로 적용할 수 있는 난이도비용대비 효과

Page 48: Patterns for effectviely documenting frameworks

48

Solution

Cookbook레시피들을 나선형 구조로 나열 “Framework overview” is often the first recipe

레시피의 구성목적절차예제

Pattern : Cookbook and Recipes

Page 49: Patterns for effectviely documenting frameworks

49

Example (JUnit)

Pattern : Cookbook and Recipes

Page 50: Patterns for effectviely documenting frameworks

50Pattern : Cookbook and Recipes

Example

Page 51: Patterns for effectviely documenting frameworks

51

Pattern : Customizable PointsDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Page 52: Patterns for effectviely documenting frameworks

52

What is Customizable Point

Hot-spot 커스터마이제이션은 사전에 정의된 개선영역에 의해서 수행된다 .

Hook변경되어야 하는 영역과 방법 : 따라야 하는 제약사항과 Hook 의 영향Hot spot 은 하나 이상의 Hook 으로 구성

Pattern : Customizable Points

Page 53: Patterns for effectviely documenting frameworks

53

Hot-spot Model

White Box Black Box

Pattern : Customizable Points

Page 54: Patterns for effectviely documenting frameworks

54

Problem

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

Pattern : Customizable Points

Page 55: Patterns for effectviely documenting frameworks

55

Force

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

Page 56: Patterns for effectviely documenting frameworks

56

Solution

별도로 커스터마이징 가능한 부분들의 목차를 제공

기능별부분이나 모듈별

잘 사용되지 않음사용법은 “ Cookbook & Recipes” 과 중복설계정보는 “ Design internals” 과 중복

Pattern : Customizable Points

Page 57: Patterns for effectviely documenting frameworks

57

Example (Junit)

Pattern : Customizable Points

Page 58: Patterns for effectviely documenting frameworks

58

Pattern : Design InternalsDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Page 59: Patterns for effectviely documenting frameworks

59

Problem

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

Pattern : Design Internals

Page 60: Patterns for effectviely documenting frameworks

60

Force

다른 목적들사용법과 설계정보 사이의 균형설계정보 복잡성의 최소화

Pattern : Design Internals

Page 61: Patterns for effectviely documenting frameworks

61

Solution

정확하고 상세한 프레임워크의 내부 설계정보를 제공

especially hot-spots. can help them better understand and enable more advanced customizations

아키텍처와 설계원칙디자인 패턴을 이용

간단한 표현풍부한 정보 제공

Pattern : Design Internals

Page 62: Patterns for effectviely documenting frameworks

62

Example (JUnit)

Pattern : Design Internals

Page 63: Patterns for effectviely documenting frameworks

63

Review : Pattern LanguagesDocumenta-

tion Roadmap

Framework Overview

Cookbook and Recipes

Graded Ex-amples

Customizable Point

Design Inter-nals

Error Recov-ery Guide

Traversable Code

Reference Guide

where is start?first recipe

how-to’s

errors

uses

illustrate

how it works?

code

index

Page 64: Patterns for effectviely documenting frameworks

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

Page 65: Patterns for effectviely documenting frameworks

65

Q & A