프로그램 매뉴얼을 만드는건 상당히 귀찮은 작업중에 하나다.
특히 각 클래스/프로퍼티/메소드에 대한 설명은 더욱더 귀찮게 한다. 왜냐~ 사용법을 일일히 만들어줘야 하기 때문이다.
소스 코딩을 하다보면 대부분 주석을 달지 않는 개발자들이 많다. 그러다 보니 나중에 매뉴얼을 작성할려고 하면 엄청난 노가다를 필요로 하게 되고, 또 해당 메소드가 왜 만들어졌는지 기억을 못하는 경우가 종종있다.
이건 개발자의 습관에 따라 다르기 때문에 우선 소스에 주석을 잘 다는걸 전재로 하겠다.
우선 자바는 이클립스라는 강력한 IDE툴이 있다. 이거 완전 물건이다. 아직 사용법을 전부 알지 못하지만 알면 알수록 개발하는데 완전 편리한 기능들이 많이 있다.
그럼 주석을 다는 방법부터 차근차근 설명하겠다.
이클립스에서 Windows > Preferences > Java > Code Style > Code Templates 를 가보면 주석과 코드를 자동생성해주는 템플릿을 정의할 수 있다.
우리는 주석만 처리 할 예정이니 코드는 그냥 두고 주석에 해당하는 각각의 항목을 보면 다음과 같다.
각각에 대한 간단한 설명과 내가 만든 샘플을 보여준다.
1. Files : 파일에 대한 주석을 생성하는 경우 사용된다.(이게 정확히 어디서 생성되는지는 사실 잘 모르겠다.)
| /* * Copyright 2009-${year} by 회사명 Corp., * All rights reserved. * * This software is the confidential and proprietary information * of 회사명Corp. ("Confidential Information"). */ /** * 1. FileName : ${file_name} * 2. Package : ${package_name} * 3. Comments : * 4. Author : ${user} * 5. DateTime : ${date} ${time} * 6. History : * ----------------------------------------------------------------- * Date | Name | Comment * ------------- ----------------- ------------------------------ * ${date} | ${user} | 최초작성 * ----------------------------------------------------------------- */ |
2. Types : 클래스에 대한 주석을 생성하는 경우
| /* * 1. 클래스명 : ${enclosing_type} * 2. 파일명 : ${file_name} * 3. 패키지명 : ${package_name} * 4. 작성자명 : ${user} * 5. 작성시간 : ${date} ${time} */ /** * <PRE> * 1. 설명 * * </PRE> */ |
3. Fields : 클래스의 프로퍼티(보통 변수라고 사용되는 부분)에 대한 주석을 생성하는 경우
| /* * 1. 필드종류 : ${field_type} * 2. 필드명 : ${field} * 3. 작성자명 : ${user} * 4. 작성시간 : ${date} ${time} */ /** * <PRE> * 1. 설명 * * </PRE> */ |
4. Constructors : 클래스 생성자에 대한 주석을 생성하는 경우
| /* * 1. 메소드명 : ${enclosing_type} * 2. 클래스명 : ${enclosing_type} * 3. 작성자명 : ${user} * 4. 작성시간 : ${date} ${time} */ /** * <PRE> * 1. 설명 * * </PRE> * ${tags} */ |
5. Methods : 클래스 메소드에 대한 주석을 생성하는 경우
| /* * 1. 메소드명: ${enclosing_method} * 2. 클래스명: ${enclosing_type} * 3. 작성자명: ${user} * 4. 작성시간: ${date} ${time} */ /** * <PRE> * 1. 설명 * * 2. 사용법 * * </PRE> * @return ${return_type} * ${tags} */ |
6. Overriding methods : 오버라이딩된 클래스 메소드에 대한 주석을 생성하는 경우
| /* * 1. 메소드명: ${enclosing_method} * 2. 클래스명: ${enclosing_type} * 3. 작성자명: ${user} * 4. 작성시간: ${date} ${time} */ /** * <PRE> * 1. 설명 * * </PRE> * ${tags} */ |
나머진 아직 사용해 보지 않아서 어디서 생성되는지 몰라 알아서 작성해보길 바란다.
위의 템플릿을 만들었으면 소스편집창에서 해당하는 부분에 커서를 옮기고 Alt + Shift + J를 누르면 해당 주석이 자동으로 생성된다.
그럼 생성된 주석에서 채워야할 빈곳을 채우면 된다.
코드부분에서는 한가지만 작성했다. New Java Files라는 부분인데, 파일에 대한 히스토리 관리를 위해 자바 파일이 새로 생성될때 주석을 자동으로 생성되도록 하기 위해 템플릿을 만들어줬다.
샘플은 다음과 같다.
| /* * Copyright 2009-${year} by 회사명Corp., * All rights reserved. * * This software is the confidential and proprietary information * of 회사명Corp. ("Confidential Information"). */ ${package_declaration} /** * 1. FileName : ${file_name} * 2. Package : ${package_name} * 3. Comments : * 4. Author : ${user} * 5. DateTime : ${date} ${time} * 6. History : * ----------------------------------------------------------------- * Date | Name | Comment * ------------- ----------------- ------------------------------ * ${date} | ${user} | 최초작성 * ----------------------------------------------------------------- */ ${typecomment} ${type_declaration} |
이렇게 모든 주석에 대한 내용 작성을 완료하고 Project > Generate JavaDoc을 실행시키면 자동으로 Html파일들이 doc폴더에 생성된다. 거기서 index.html을 실행 시키면 다음과 같은 매뉴얼이 작성된것을 볼수 있다.
템플릿은 첨부한 파일을 받아서 Import해서 사용해도 무방하다.
codetemplates.xml