c++ API디자인 ch9. 발표자료

9장. 문서화아꿈사

overview

재사용을 말로 하기는 쉽지만 정작 그것을 실행하기란 어려운 일이다. 훌륭한 설계와 잘 정리된 문서화 이 둘 모두를 요구하기 때문이다. 문서화 없이 재사용된 컴포넌트는 절대 볼 수 없을 것이다.

-데이비드 L. 파르나스

9.1 문서화의 이유

-API는 기능적 명세서

class RGBColor{RGBColor(float, float, float);~RGBColor();

float Red() const;float Green() const;float Blue() const;void Set(float, float, float);

}

- 무엇을 알 수 있었을까요?메서드가 정의하는 리턴 타입, 파라미터하지만, 클래스가 무엇을 수행하는지는 알기

힘듭니다.

/// 하나의 RGB(Red, Green, Blue)색을 표현한다./// (0,0,0)은 검은색 그리고 (1,1,1)은 흰색class RGBColor{

/// 0부터 1사이에 있는 float값을 이용해서 RGB색을 생성RGBColor(float red, float green, float blue);~RGBColor();

//색의 빨강색 요소를 리턴한다. 값의 범위는 0부터 1사이다.float Red() const;float Green() const;float Blue() const;void Set(float, float, float);

}

9.1.2 Documenting the Interface’s Contract

계약 프로그래밍?소프트웨어 컴포넌트는 자신들이 제공할 서

비스에 대한 계약,의무를 제공하며 이 서비스의 클라이언트는 컴포넌트를 통해 그 계약에 합의 한다는 것?

9.1.2 Documenting the Interface’s Contract

client

컴포넌트 서비스

클라이언트는 서비스를 계약했다

9.1.2 Documenting the Interface’s Contract

-계약 모델의 원칙1. 사전조건2. 사후조건3. 클래스 불변조건

9.1.2 Documenting the Interface’s Contract

1. 사전조건클라리언트는 함수를 호출하기 전에 요구된 사전조건들을 만족시켜야한다.

9.1.2 Documenting the Interface’s Contract

2. 사후조건함수는 동작이 완료되면 특정조건이 만족될 것이라는 점을 보장한다.

9.1.2 Documenting the Interface’s Contract

3. 클래스 불변조건클래스의 모든 인스턴스가 반드시만족시켜야 하는 제약조건

////// \brief Calculate the square root of a floating point number./// \pre value >= 0/// \post fabs((result * result) value) < 0.001///double SquareRoot(double value);

9.1.2 Documenting the Interface’s Contract

상속된 클래스의 사전조건은 그 부모 클래스가 가진것보다 강하지 않고 오히려 약해 질 수 있다.

-켄 퓨

9.1.3 행동 변화에 대한 의사소통

소스코드가 바뀌면문서화도 고쳐주어라

9.1.4 문서화의 대상

API의 모든 public요소를 문서화 해야한다.클래스, 함수, 열거형, 상수와, 타입정의,파라미터, 리턴값,메서드의 행동 뿐만 아니라, 나머지API관계에 대한 설명 등등

9.2 문서화의 유형

- 사용자가 직접 참여

9.2 문서화의 유형

- 사용자가 직접 참여

9.2 문서화의 유형

-자동화된 API문서화주석을 자동으로 생성해주는 툴주석을 추출해서, 문서화해주는 툴

Doxygen, Groc, Swagger

9.2.2 개요 문서화

-API의 고차원적 개념도(다이어그램)-핵심 개념, 특징과 용어-API를 사용하기 위한 시스템 요구사항-소프트웨어 설치,설정방법-피드백, 버그 신고는?

9.2.3 예제와 튜토리얼

-간단하고 쉬운 예제-작업 데모-튜토리얼과 세부 설명-사용자 참여-FAQ

9.2.5 라이선스 정보

1. 등록상표소유권이 공급자에 귀속소스코드를 제공 X라이선스 비용 요구역공학, 사용자 컴퓨터수, 개발자수 제한

9.2.5 라이선스 정보

2. 자유 오픈 소프트웨어어떤 제약없이 수정, 배포 복제 가능

-카피레프트-자유형

9.4 DOXYGEN

9.4 DOXYGEN

9.4 DOXYGEN

9.4 DOXYGEN - 주석/** ///* ... text … /// … text ...*/ ///

/*! //!* ... text … //! … text ...*/ //!

9.4 DOXYGEN - 파일주석////// \file <filename>////// \brief <brief description>////// \author <list of author names>/// \date <date description>/// \since <API version when added>////// <description of module>////// <license and copyright information>///

9.4 DOXYGEN - 클래스 주석////// \class <class name> [header file] [header name]////// \brief <brief description>////// <detailed description>////// \author <list of author names>/// \date <date description>/// \since <API version when added>///

9.4 DOXYGEN - 메서드 주석////// \brief <brief description>////// <detailed description>////// \param[in] <input parameter name> <description>/// \param[out] <output parameter name> <description>/// \return <description of the return value>/// \since <API version when added>/// \see <methods to list in the see also section>/// \note <optional note about the method>///

End of Document