Create document automatically (1)

코드 베이스 문서 자동화.
(Code-based document automation)
2018.09.17
Data Biz Part
안상준

Automation…
• 제어 시스템과 다른 정보기술을 조화롭게 사용하여 산업 기계류
와 공정을 제어, 사람이 관여할 필요를 줄이는 것이다.
(Wikipedia)
• Tool을 잘 사용하여,
• Process를 잘 핸들링 해서,
• 개발자의 시간을 줄이자.
https://ko.wikipedia.org/wiki/%EC%9E%90%EB
%8F%99%ED%99%94

문서는 왜 써야 되나?
인간은 망각의 동물이다.
개발자들의 대부분의 시간은 코드를 이해하는데 소비합니다.

개발자들이 소모하는 시간

개발 완료 후 몇 주가 지나 버그가 발견 되었지만, 코드를 고치려니
내가 어떻게 구현 했었는지 정확히 기억이 나질 않네요.

코드를 읽으니 이전의 기억이 하나 둘 되살아 납니다.
이제 버그를 수정하는 건 1도 아니에요.

이런 일은 이후에도 계속 반복됩니다..

시간이 흐르면서 코드의 복잡도는 증가했고, 나중에는 몇 일을 보
아도 구조를 잘 모르는 일이 생기고 말았어요.

어떻게 하면 기억을 좀 더 쉽게 되살릴 수 있을까요?

문서를 작성하면 효과가 있습니다.
문서를 읽으면 코드를 훨씬 빨리 파악할 수 있어요.

이젠,
완성된 코드와 더불어 문서도 소중한 결과물 입니다.

하지만 문서 작성도 비용 아닌가요?
맞아요. 문서 작성에도 큰 비용이 소모 됩니다.
하지만 코드가 문서 자체가 된다면 어떨까요?

코드 버전 별로 문서 버전을 관리할 필요가 없습니다.
코드만 관리하면 문서 관리까지 되는 것이니까요.

어떻게 그런 일이 가능하죠?
?

Doxygen 주석 문법을 사용하여 코드에 주석을 달면 됩니다.
Syntax도 어렵지 않아요. 몇 분이면 충분합니다.

그럼 어서, 사용법을 알려주세요!
그럼 어떻게 사용하면 되는지 알려드리겠습니다 !
ㄲㄲ

Ubuntu에서 단 몇 줄이면 Generate 할 수 있어요.
Configure 설정을 통해 다양하게 튜닝이 가능해요.

커멘드 몇 줄로 문서가 생성 되었어요. 진짜 생성된 것이 맞나요?

네 , 진짜 생성 되었어요 :)

Configure 설정을 통해 좀 더 Rich한 API명세 Format을 만들 수 있지
만,
상세한 건 다음 시간에 해보도록 하죠(TMI).

이제 API명세 자동화는 어떻게 하는지 알겠어요 !
그럼 혹시 Diagram은 자동화 할 수 없나요?

그래서 준비 했습니다.
Plant UML
http://plantuml.com/sequence-diagram

Plant UML이 뭐에요? 처음 들어봐요.
Plant UML은 Code Based로 Diagram을
자동으로 그려주는 Auto Generate Tool 입니다.(Java)
http://plantuml-depend.sourceforge.net/

Doxygen과 동일하게 Syntax가 굉장히 쉬워요.
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml

우리가 매일 쓰는 Jira Page(Collab)에서도
Plant UML을 사용할 수 있다고요?

Select macro - Feat. (Ctrl + Shit + A)

위의 예제를 복사 붙여 넣은 후, 저장만 하면 됩니다.

그럼 조금 더 난이도 있는 UML을 보여주세
요!
아직 간지가 부족해요.
그래서, 코드 분석하는 겸 그림(UML)을 하나 그려봤습니다.
(Route Lambda)

http://collab.lge.com/main/pages/viewpage.action?pa
geId=871261952

Class Diagram만 만들 수 있나요?
다른 Diagram들은요?

Plant UML은 Sequence, Use Case, Activity(Beta), Component,
State, Object, Deployment(Beta) Diagram 을 지원 합니다.
http://plantuml.com/sequence-diagram

그럼 Plant UML에서 만든 Diagram을
Doxygen에 붙여 넣는 것도 가능한가요?

Diagram + API 명세 = 소프트웨어 설계 명세서(SDD)
자동(Automation)으로 산출 문서 하나가 생성 됩니다.
https://ko.wikipedia.org/wiki/%EC%86%8
C%ED%94%84%ED%8A%B8%EC%9B
%A8%EC%96%B4_%EA%B0%9C%EB%
B0%9C_%ED%94%84%EB%A1%9C%E
C%84%B8%EC%8A%A4

열심히 만든 주석으로 API 명세가 만들어 지고, 거기에 UML까지 붙
이면
SDD 문서 하나가 Build할 때 마다 만들어 지겠죠?

감사합니다.
https://www.pinterest.co.kr/

Create document automatically (1)

Recommended

Recommended

More Related Content

Similar to Create document automatically (1)

Similar to Create document automatically (1) (20)

Create document automatically (1)