9장. 문서화
아꿈사
overview
재사용을 말로 하기는 쉽지만 정작 그것을 실행
하기란 어려운 일이다.
훌륭한 설계와 잘 정리된 문서화 이 둘 모두를
요구하기 때문이다.
문서화 없이 재사용된 컴포넌트는 절대 볼 수 없
을 것이다.
-데이...
9.1 문서화의 이유
-API는 기능적 명세서
class RGBColor{
RGBColor(float, float, float);
~RGBColor();
float Red() const;
float Green() const;
float Blue() const;
vo...
- 무엇을 알 수 있었을까요?
메서드가 정의하는 리턴 타입, 파라미터
하지만, 클래스가 무엇을 수행하는지는 알기
힘듭니다.
/// 하나의 RGB(Red, Green, Blue)색을 표현한다.
/// (0,0,0)은 검은색 그리고 (1,1,1)은 흰색
class RGBColor{
/// 0부터 1사이에 있는 float값을 이용해서 RGB색을 ...
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) val...
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>
/// dat...
9.4 DOXYGEN - 클래스 주석
///
/// class <class name> [header file] [header name]
///
/// brief <brief description>
///
/// <det...
9.4 DOXYGEN - 메서드 주석
///
/// brief <brief description>
///
/// <detailed description>
///
/// param[in] <input parameter n...
End of Document
Upcoming SlideShare
Loading in...5
×

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

1,579
-1

Published on

API design for C++

Published in: Education
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,579
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
10
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

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

  1. 1. 9장. 문서화 아꿈사
  2. 2. overview 재사용을 말로 하기는 쉽지만 정작 그것을 실행 하기란 어려운 일이다. 훌륭한 설계와 잘 정리된 문서화 이 둘 모두를 요구하기 때문이다. 문서화 없이 재사용된 컴포넌트는 절대 볼 수 없 을 것이다. -데이비드 L. 파르나스
  3. 3. 9.1 문서화의 이유 -API는 기능적 명세서
  4. 4. class RGBColor{ RGBColor(float, float, float); ~RGBColor(); float Red() const; float Green() const; float Blue() const; void Set(float, float, float); }
  5. 5. - 무엇을 알 수 있었을까요? 메서드가 정의하는 리턴 타입, 파라미터 하지만, 클래스가 무엇을 수행하는지는 알기 힘듭니다.
  6. 6. /// 하나의 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); }
  7. 7. 9.1.2 Documenting the Interface’s Contract 계약 프로그래밍? 소프트웨어 컴포넌트는 자신들이 제공할 서 비스에 대한 계약,의무를 제공하며 이 서비스의 클라이언트는 컴포넌트를 통해 그 계약에 합의 한다는 것?
  8. 8. 9.1.2 Documenting the Interface’s Contract client 컴포넌트 서비스 클라이언트는 서비스를 계약했다
  9. 9. 9.1.2 Documenting the Interface’s Contract -계약 모델의 원칙 1. 사전조건 2. 사후조건 3. 클래스 불변조건
  10. 10. 9.1.2 Documenting the Interface’s Contract 1. 사전조건 클라리언트는 함수를 호출하기 전에 요구된 사전조건들을 만족시켜야한다.
  11. 11. 9.1.2 Documenting the Interface’s Contract 2. 사후조건 함수는 동작이 완료되면 특정조건이 만족될 것이라는 점을 보장한다.
  12. 12. 9.1.2 Documenting the Interface’s Contract 3. 클래스 불변조건 클래스의 모든 인스턴스가 반드시 만족시켜야 하는 제약조건
  13. 13. /// /// brief Calculate the square root of a floating point number. /// pre value >= 0 /// post fabs((result * result) value) < 0.001 /// double SquareRoot(double value);
  14. 14. 9.1.2 Documenting the Interface’s Contract 상속된 클래스의 사전조건은 그 부모 클래스가 가진것보다 강하지 않고 오 히려 약해 질 수 있다. -켄 퓨
  15. 15. 9.1.3 행동 변화에 대한 의사소통 소스코드가 바뀌면 문서화도 고쳐주어라
  16. 16. 9.1.4 문서화의 대상 API의 모든 public요소를 문서화 해야한다. 클래스, 함수, 열거형, 상수와, 타입정의, 파라미터, 리턴값, 메서드의 행동 뿐만 아니라, 나머지 API관계에 대한 설명 등등
  17. 17. 9.2 문서화의 유형 - 사용자가 직접 참여
  18. 18. 9.2 문서화의 유형 - 사용자가 직접 참여
  19. 19. 9.2 문서화의 유형 -자동화된 API문서화 주석을 자동으로 생성해주는 툴 주석을 추출해서, 문서화해주는 툴 Doxygen, Groc, Swagger
  20. 20. 9.2.2 개요 문서화 -API의 고차원적 개념도(다이어그램) -핵심 개념, 특징과 용어 -API를 사용하기 위한 시스템 요구사항 -소프트웨어 설치,설정방법 -피드백, 버그 신고는?
  21. 21. 9.2.3 예제와 튜토리얼 -간단하고 쉬운 예제 -작업 데모 -튜토리얼과 세부 설명 -사용자 참여 -FAQ
  22. 22. 9.2.5 라이선스 정보 1. 등록상표 소유권이 공급자에 귀속 소스코드를 제공 X 라이선스 비용 요구 역공학, 사용자 컴퓨터수, 개발자수 제한
  23. 23. 9.2.5 라이선스 정보 2. 자유 오픈 소프트웨어 어떤 제약없이 수정, 배포 복제 가능 -카피레프트 -자유형
  24. 24. 9.4 DOXYGEN
  25. 25. 9.4 DOXYGEN
  26. 26. 9.4 DOXYGEN
  27. 27. 9.4 DOXYGEN - 주석 /** /// * ... text … /// … text ... */ /// /*! //! * ... text … //! … text ... */ //!
  28. 28. 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> ///
  29. 29. 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> ///
  30. 30. 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> ///
  31. 31. End of Document
  1. Gostou de algum slide específico?

    Recortar slides é uma maneira fácil de colecionar informações para acessar mais tarde.

×