2 Results for '문서화'

  1. 2009.01.30 라이브러리 문서화의 중요성 (2)
  2. 2008.11.05 Sandcastle을 사용한 간단 문서화 (8)

요즘 실버라이트용 DI(Dependency Injection) 프레임워크로 Pattern&Practice 팀에서 제공하는 Unity Application Block과 독특한 특징을 가진 Ninject, 이 둘을 보고 있죠. 사실 DI의 원리나 구성은 대략 파악했다고 생각하는데 실제 구현은 참 난감한 부분이 많은 것 같아요. 그래서 우리는 이런 공개된 프레임워크의 덕분에 좀 더 쉬운 삶-바로 제가 추구하는 그것!-을 살 수 있어요.

여튼 이 둘은 서로 스타일이 꽤 달라요. 우선 네이밍 부터가 꽤 달라서 이게 과연 같은 패턴을 사용하는 그것이 맞나 싶을 정도. 아주 조금씩만 써보고 있어서 아직 확실하게 감은 못잡았지만 공부하면서 느끼는 차이는 바로 문서화의 차이에요.

Unity는 마이크로소프트의 P&P에서 나온 만큼 철저하게 MSDN 스타일로 구성되어 있죠. MSDN의 장점은 어떤 라이브러리를 매우 광범위하고 자세하게 기술하고 있다는 점인데요 반면 단점은 Getting started를 봐도 딱 그 정도까지만 쓸 수 있을 뿐 그 이상의 기능을 구현하려면 어떤 클래스를 어떻게 사용할지 찾기가 꽤 어렵다는 점이죠. 그래도 최근엔 HOWTO 토픽도 많이 생기고 해서 이런 점은 많이 해소 되었지만, 그래도 여전히 문서가 너무 딱딱해서 어느정도 기합을 넣고 보지 않으면 잘 읽히지가 않아요.

Ninject는 일단 메인 사이트 부터가 굉장히 팬시해서 둘러보는데 부담이 없어요. 그리고 Ninject는 MSDN처럼 완전히 정리된 문서따위는 없지만 Wiki를 통해 아주 깔끔하게 스텝별로 익힐 수 있도록 되어 있어요. 이게 중요한데요, Ninject는 Ninject를 설명할 때 기능 하나하나에 대한 사용법이나 설명을 독립적으로 하는게 아니라 단계별로 기본적인 사용법과 함께 Ninject가 어떤 부분에 주안점을 가지고 있는지 이해할 수 있도록 구성되어 있죠.

베스트 케이스라면 Getting started를 Ninject스타일로 친절하게 구성하고 세부적인 레퍼런스를 MSDN 스타일로 구성하는 거지만 둘 중 하나를 선택하라면 Ninject 스타일의 손을 들어주고 싶네요. 왜냐면 프레임워크나 라이브러리라는 건 일단 처음 사용하기가 굉장히 괴롭거든요. 일종의 진입 장벽이랄까요? 그런 걸 쉽게 덜어주고 그 라이브러리의 설계 철학이나 흐름을 잡는게 중요하다고 봐요.

왜 이런 소릴 하고 있냐면…

Ninject에서는 모듈(Unity의 컨테이너 개념)에 인터페이스와 클래스의 바인딩을 등록할 때 아주 간단하면서도 유용한 조건을 붙여서 하나의 인터페이스에 여러개의 클래스를 조건에 따라 자동으로 인젝션 되도록 되어 있어요. 예를 들면,

public class Swordsman { 
  [Inject] public IWeapon Weapon { get; set; } 
}

public class Ninja { 
  [Inject] public IWeapon MeleeWeapon { get; set; } 
  [Inject, Range] public IWeapon RangeWeapon { get; set; } 
}

Bind().To(); 
Bind().To().Only(When.Context.Target.HasAttribute());

이건 “IWeapon이라는 인터페이스를 Sword클래스와 Shuriken(수리검^^) 클래스에 바인딩을 하되 Context.Target(인젝션 대상, 여기에서는 Weapon, MeleeWeapon, RangeWeapon과 같은 프로퍼티)이 RangeAttribute라는 어트리뷰트를 가지고 있을 때만 Shuriken을 바인딩 해라”를 의미해요. 정말 기가 막히게 팬시하면서 읽기 쉬운 코드 아닌가요? 거의 영어 문장을 읽는 것과 비슷하게 느껴질 정도로요.

또한 예제 코드 역시 Foo나 Bar 따위가 아니라 검사(Swordman)과 닌자(Ninject를 떠올리는!)가 각각 자신의 역할에 맞게 사용할 무기들을 선택하는 과정이 머리속에 그려지도록 잘 선택되었고요.

다른 방법의 예제를 보면

public class Ninja { 
  [Inject] public IWeapon MeleeWeapon { get; set; } 
  [Inject, Tag("range")] public IWeapon RangeWeapon { get; set; } 
}

Bind().To(); 
Bind().To().Only(When.Context.Tag == "range");

비슷한데 Tag라는 미리 지원되는 어트리뷰트를 가지고 문자열 비교를 할 수 있게 한거에요. 이러면 매번 어트리뷰트를 새로 만들지 않아도 되니 편리하겠죠. 마찬가지로 문장은 정말 쉽게 읽히고요.

거기에 한 단계 더 생각해서, 단지 인젝션 대상의 이름 규칙(convention)만으로도 바인딩 할 수 있게 지원하죠.

public class Service { 
  public Service(ISource remoteSource, ISource localSource) { 
    //... 
  } 
}

Bind().To().Only(When.Context.Target.Name.BeginsWith("remote")); 
Bind().To().Only(When.Context.Target.Name.BeginsWith("local"));

Service라는 클래스는 생성될 때 두 개의 ISource를 받죠. 아래의 바인딩 문은 이 클래스에 인젝션할 때 “타겟이 remote라는 이름으로 시작할 때”, “타겟이 local이라는 이름으로 시작할 때”라는 조건을 붙인 걸 읽을 수 있어요. (진짜 볼 수록 감탄…)

참 쉽죠? (ㅋㅋ)

반면 Unity에서 비슷하게 하나의 컨테이너에 하나의 인터페이스를 여러 개의 클래스와 바인딩하고 싶은데 도무지 어디에서 그런 설정을 해야할지 난감하네요. 아마도 Configuration이라는 클래스를 상속받아 구현하는 것 같은데 실버라이트용에서는 그 Configuration이 빠졌다고 하는군요. 여튼 “동적인 조건부 인젝션”을 어떻게 할지 난감해요.

네, 솔직히 저는 Ninject의 손을 들어주고 있는데요, 다만 Unity for Silverlight는 단일 어셈블리에 용량도 조금이나마 작아서 딱 DI만 쓴다고 봤을 때 좀 더 가벼운데 Ninject는 3개의 어셈블리에 용량도 약간 더 커요. 그래서 Unity쪽도 해보고 둘 중에 하나를 선택하자..는 기분으로 써보고 있는데 이놈의 Unity 문서는 읽다보면 스르르 잠에 빠져서 진도가 안나가네요 ㅠ.ㅜ

그래서 오늘의 결론.

라이브러리 문서화를 잘 합시다. 이왕이면 단계별로 가장 핵심적인 내용을 익힐 수 있도록!
AND
Unity 써보신 분 조건적 인젝션 바인딩을 컨테이너에 어떻게 넣는지 좀 알려줍쇼 ㅠ.ㅜ 굽신굽신 oTL oTL

저작자 표시 동일 조건 변경 허락
신고
Posted by gongdo

오늘은 땡스빌을 외치며 시작하죠. 그리고 코드 플렉스에도 감사를.

개발자를 지긋지긋하게 괴롭히는 것 중 하나는 문서 작업이죠. 어쩌겠습니까 뭐.

최근에 회사에서 라이브러리를 정리하면서 '위키로 라이브러리를 정리하자!'하고 막상 위키를 개설해 놨더니… 뭐 결과는 다 아시잖아요? 문서 만드는게 죽도록 귀찮은 일이라서…

이럴 시간에 한 줄이라도 더 쓰지 OTL

음음.

그래서 한동안 잊고 있었던 샌드캐슬 프로젝트를 혹시나 하고 기웃거려 봤더니 코드플렉스로 죄다 이사를 갔더군요. 그리고 기대를 져버리지 않고 닷넷 3.5까지 잘 지원을 하고 있었어요. 앗싸~

여튼, 슬슬 이 글 쓰는 것도 귀찮아지고 있어서 아주 초간단하게 준비물과 해야 할 일을 주욱 늘어놓고 끝내도록 하죠.

준비물

[필수]

[툴]

[옵션]

와우, 죄다 코드 플렉스로 이사갔네요. 요즘은 마이크로소프트랑 관계된 오픈 소스 프로젝트는 거의 대부분 코드 플렉스에 있는 것 같아요.

간단하게 설명하자면 Sandcastle은 일종의 라이브러리이고 Sandcastle을 사용하여 여러 가지 프로젝트들이 각기 다른 방법으로 문서화나 빌드를 하는 툴 혹은 프로젝트를 진행하고 있죠.

실제로 사용할 툴은 Sandcastle Help File Builder(SHFB) 또는 DocProject에서 진행하고 있는 건데요 서로 다른 특성을 가지고 있어요.

SHFB는 GUI 툴로 프로젝트 파일을 추가하고 연관된 어셈블리 들을 넣어주면 헬프 파일을 만들어주는데 단점은 의존성 있는 어셈블리를 일일이 추가해 줘야 한다는 것과 편집 옵션이 전체 헬프 파일 서머리와 네임스페이스 별 서머리만을 지원하고 나머지는 그냥 기본이라는 점. (이 외에 다른 방법이 있는 것 같은데 귀찮습니다. … ㅠ.ㅜ)

이에 반해 DocProject는 의존성 있는 어셈블리를 별도로 지정할 수 있어서 간편하고 좀 더 편리한 편집 툴도 제공해서 더 좋은 것 같아요. 하지만 C# 프로젝트 형식이라서 별도의 솔루션을 만드는 것이 좋고 해서 스탠드얼론 방식을 좋아하는 분에게는 별로겠죠.

여튼 선택은 자유…이지만 설명은 DocProject만 할께요.

헬프 파일 스타일은 헬프 파일의 디자인의 몇몇 템플릿인데요, MSDN말고도 다른 스타일로 할 수 있죠. 이건 뭐 말 그대로 옵션.

마지막으로 MS 헬프 2.0 형식의 파일(.HsX)는 CHM과는 다르게 곧바로 볼 수 없고 별도의 등록 과정을 거쳐야만 Document Explorer에서 볼 수 있죠. 근데 이게 또 만만치가 않아요. =_=;

 

설치 과정

 

사용 방법

DocProject를 기준으로, 기본적으로 릴리즈 노트에 잘 설명이 되어 있으니,

…라고 하고 싶습니다만, 실버라이트용 프로젝트에서는 약간 더 손대야 할 부분이 있어서 그 부분만 언급하고 넘어갈께요;; 길어서 접어둡니다.

더보기

저작자 표시 동일 조건 변경 허락
신고
Posted by gongdo


티스토리 툴바