새로운 글
새로운 덧글

주석은 코드를 더 읽기 쉽고, 유지보수하기 쉽게 할 수 있는 가장 기본적인 요소 중 하나입니다.

특히 팀단위로 개발하거나, 오랫동안 유지보수해야 하는 경우 진가를 발휘합니다.

 

이 글에서는 주석을 좀 더 효과적으로 달고, 내용을 문서화하는 방법을 소개합니다.

XMLDoc과 JavaDoc 주석의 특징과 추가 방법, 문서화 하는 방법을 알아봅니다.

 

XMLDoc과 JavaDoc 주석 추가

XMLDoc 주석

XMLDoc 주석의 특징

  • 3 중 슬래시(///)로 시작
  • XML 태그로 작성
  • 코드 에디터의 헬프 인사이트에 표시
  • XML 태그로 가독성이 다소 떨어짐

XML 주요 항목

  • <summary> 함수 또는 클래스에 대한 설명
  • <param name="파라메터 이름"> 파라메터에 대한 설명
  • <returns> 함수의 반환 값 설명
  • < exception cref="예외 유형"> 메소드에서 전달되는 예외

예시

 

 

XMLDoc의 특징

XML Doc 주석 추가 시 코드 에디터의 헬프 인사이트에 표시됩니다.

단, 선언부(interface 영역)에 XML Doc 추가 시에만 표시됩니다.

 

 

한가지 팁으로, 코드 템플릿에 템플릿을 추가하면 필요시 코드에디터에 주석을 쉽게 추가 할 수 있습니다.

 

 

(Ctrl + J > 키워드 입력 또는 키워드 입력 > Ctrl + J)

 

코드 템플릿 추가방법

View > Tool Windows > Templates 메뉴 선택

New Code Template 버튼 클릭

아래 코드 참고해 XML 태그 수정 후 저장(예> xmldoc.summary.xml)

 

 

 

 

또는 위 XML 태그로 xml 파일 생성(별도의 텍스트 에디터에서) 및 저장

템플릿 디렉토리에 xml 파일 복사

(10.3 기준 템플릿 디렉토리 : C:\Program Files (x86)\Embarcadero\Studio\20.0\ObjRepos\en\Code_Templates\Delphi)

 

JavaDoc 주석

자바의 주석 형식으로 주석을 작성하면, 별도 프로그램을 이용 문서화(HTML, CHM, PDF 등)가 가능합니다.

JavaDoc 주석의 특징

  • 블록 주성({** 시작 *}로 끝) 또는 한줄 주석(3 중 슬래시(///)로 시작)
  • 주석의 속성(태그)은 @으로 시작
  • XMLDoc에 비해 주석 가독성이 높음(짧음)

JavaDoc 주요 태그

  • 태그 없는 경우 함수에 대한 설명
  • @author 작성자
  • @version 버전
  • @param 메소드 파라메터 설명
  • @return 반환 값 설명
  • @throws 메소드에서 전달되는 예외

예시

 

 

 

주석 문서화

추가한 주석을 문서화(문서로 내보내기)하는 방법을 알아봅니다.

XMLDoc 주석 문서화

XMLDoc을 문서화 하기 위해서는 Model을 생성해야 합니다.

Projects 팬에서 Model View 탭을 선택 후 모델을 생성합니다.

 

 

Model View에서 문서화할 대상(프로젝트 또는 유닛) 선택 후 팝업메뉴에서 "Generate Documentation..." 메뉴를 선택 합니다.

 

 

문서화 범위(Scope) 및 옵션(Options)를 선택 후 [OK] 버튼을 클릭 합니다.

 

 

 

결과 예시

다음과 같이 XMLDoc 주석을 추가했습니다.

 

 

 

생성된 HTML은 다음과 같습니다.

 

 

JavaDoc 주석 문서화

JavaDoc 포맷의 주석을 문서화 하기 위해서는 별도의 프로그램을 이용해야 합니다.

이 글에서는 DelphiCodeToDoc를 이용해 문서화합니다.

 

DelphiCodeToDoc은 델파이로 제작된 오픈소스(GPL)로 자유롭게 설치하고 필요한 기능을 수정해 기여할 수 있습니다.

문서화 포맷으로 CHM, HTML, PDF를 지원합니다.(Configuration 화면의 Output options > Output Format에서 지정)

결과물이 썩 이쁘지는 않지만, 그렇게 나쁘지도 않습니다.

 

DelphiCodeToDoc(DCTD) 설치

DelphiCodeToDoc(DCTD) 실행

DelphiCodeToDoc.exe 실행 후 [New] 버튼 클릭(또는 File > New 메뉴 선택)

 

 

마법사 페이지에서 옵션 설정 및 대상 파일(또는 디렉토리) 선택 및 추가 후 [Finish]

 

 

메인화면에서 [Check and Build] 버튼 클릭(또는 Project > Check and Build 메뉴 선택)

 

 

빌드 시 CHM 도움말이 표시되고, 지정된 경로(Ouput Folder)에 지정된 포맷

 

결과 예시

DCTD에서 설정한 프로젝트 관련 내용 표시

프로젝트 이름을 한글로 설정 시 좌측 내용트리에 한글깨짐 현상이 있으나, 문서내에서는 정상출력 확인

 

 

 

프로시저에 대한 문서

@author, @version 태그 추가했지만, 문서에 표시되지 않음

 

 

웹으로 내보내기한 Unit에 대한 문서

 

 

총평

XMLDoc과 JavaDoc 주석을 추가하고 문서화 하는 내용을 살펴봤습니다.

 

XMLDoc은 주석에 XML 태그가 있어 코드내의 가독성은 떨어지지만, 헬프 인사이트에 표시된다는 장점이 있습니다.(단, 선언부에 주석을 달아야 합니다.

JavaDoc은 코드내 주석에 대한 가독성이 상대적으로 높지만, 헬프 인사이트 등으로 표시되지 않습니다.

 

문서의 결과물은 개인적으로 JavaDoc의 결과물이 더 다양하고 깔끔하다고 생각합니다.

또한 오픈소스여서 필요한 경우 직접 수정해 필요한 기능을 확장할 수 있습니다.(물론 쉽지 않습니다.)

 

위 내용을 종합적으로 판단한다면 저는 개인적으로 JavaDoc을 선호합니다. 이유는 XMLDoc은 선언부에 주석을 달아야 하기 때문에 구현부를 전체적으로 살펴볼때 JavaDoc의 주석 형식이 더 유용할 것으로 판단됩니다.

(또는 2개의 방식을 번갈아가며 사용해도 좋을 것 같습니다. 선언부는 XMLDoc, 구현부는 JavaDoc)

 

여러분들도 여러분들의 환경에 맞는 방식을 선택 해보시기 바랍니다.

 

참고로 위 방법 외에도 doxygen 등과 같은 주석 문서화하는 방법이 많습니다.

그리고 JavaDoc 주석을 문서화 하는 프로그램도 많을 것입니다.

혹시 아는 주석 문서화 방법이나 문서화 프로그램이 있다면 댓글로 알려주시면 감사하겠습니다.

 

참고 링크

번호 제목 글쓴이 날짜 조회 수
공지 [10.3 리오][업데이트 3] What's NEW! 신기능 자세히 보기 관리자 2019.11.22 1407
공지 RAD스튜디오(델파이,C++빌더) - 고객 사례 목록 관리자 2018.10.23 3624
공지 [데브기어 컨설팅] 모바일 앱 & 업그레이드 마이그레이션 [1] 관리자 2017.02.06 6441
공지 [전체 목록] 이 달의 기술자료 & 기술레터 관리자 2017.02.06 2881
공지 [프로그래밍 강의] 2019.8~2019.12 관리자 2015.01.22 9920
공지 RAD스튜디오(델파이, C++빌더) - 시작하기 관리자 2015.06.30 16065
공지 RAD스튜디오(델파이,C++빌더) - 모바일 앱 개발 사례 (2019년 11월 업데이트 됨) 험프리 2014.01.16 153396
218 [도서/PDF/소스코드] 델파이 Begin...End - 9장. 예외(Exception) 처리 [1] file 관리자 2019.08.19 137
217 [도서/PDF/소스코드] 델파이 Begin...End - 8장. 필드 에디터 file 관리자 2019.08.19 111
216 [도서/PDF/소스코드] 델파이 Begin...End - 6장. 데이터베이스 프로그래밍 개요 file 관리자 2019.08.19 126
215 [도서/PDF/소스코드] 델파이 Begin...End - 7장. BDE를 사용한 데이터베이스 프로그래밍 [1] file 관리자 2019.08.19 126
214 [도서/PDF/소스코드] 델파이 Begin...End - 5장. 디버깅 사용하기 file 관리자 2019.08.09 118
213 [도서/PDF/소스코드] 델파이 Begin...End - 4장. 컴포넌트 라이브러리와 패키지 file 관리자 2019.08.09 109
212 [도서/PDF/소스코드] 델파이 Begin...End - 3장. 컴포넌트와 친해지기 [1] file 관리자 2019.08.09 112
211 [도서/PDF/소스코드] 델파이 Begin...End - 2장. 폼의 특성과 띄우기 [1] file 관리자 2019.08.09 120
210 [도서/PDF/소스코드] 델파이 Begin...End - 1장. 델파이로 프로젝트 시작하기 [1] file 관리자 2019.08.08 173
209 [도서/PDF/소스코드] 델파이 Begin...End - 0장. 책 소개. 저자 소개. 목차 file 관리자 2019.08.06 154
208 [10.3 리오][업데이트 2] 델파이에서 맥OS 64-bit 애플리케이션 개발이 가능합니다. 관리자 2019.07.25 168
» 델파이 코드 주석 추가 및 문서화 방안 험프리 2019.05.30 321
206 [도서/PDF/소스코드] 시작하는 사람들을 위한 델파이 프로그래밍-모듈 0. 책 소개. 저자 소개. 목차 file 관리자 2019.02.20 1073
205 [10.3 리오] 리눅스 컴파일러에 non-ARC 메모리 모델이 적용됩니다. 험프리 2018.12.04 152
204 [10.3 리오] 델파이 언어의 새로운 변화: 인라인 변수 선언 관리자 2018.11.12 1712
203 [고객사례-게임, 델파이] 오목게임 관리자 2018.10.23 435
202 델파이로 3D 크레딧 스크롤 구현하기(소스제공) file 험프리 2018.05.09 502
201 패키지 개발방식과 DLL개발방식의 차이와 장단점 김원경 2018.05.02 1395
200 RFID 리더(한미IT RF Prisma) 연동하기 - 델파이에서 JAR 이용 [1] 험프리 2017.12.19 829
199 수원과학대 학생이 델파이로 개발한 '축구 리그 앱' 관리자 2017.11.24 729


광고 모듈이 설치되어 있지 않아 실행을 중단합니다..