코드쓰는사람

개발자들이 개발하면서 제일 싫어하는 것 중 하나가 바로 문서작업입니다.

그래서 문서작업을 따로 하지 않아도 되도록 Java 개발자들을 위한 JavaDoc 이라는게 있죠. JavaDoc 은 대충 다음의 형식을 따릅니다.

/**
* Sorts some Array
*
* @param arr the Array
* @exception SortArgumentException if arr is null
*/

public void sort(Array arr) {
....
}

위와 같이 메소드를 정의하면서 특정 형식에 맞추어 주석을 표기하면 javadoc 이라는 실행파일이 알아서 문서로 만들어줍니다. 소스코드의 가독성도 늘리고, 문서작업도 한꺼번에 되고, 메소드나 함수의 내용을 기억하기도 쉬우니까 1석 3조가 되는거죠.JavaScript 쪽에도 비슷한 것으로 ScriptDoc 이라는게 있습니다. 공식 사이트는 http://www.scriptdoc.org/ 입니다.

스크립트 파일의 헤더쪽에 포함되는 내용은 @version, @author, @projectDescription, @sdoc, @namespace 등이 있으며 다음과 같이 사용합니다.

/**
* @projectDescription Joe Smith's wonderful JavaScript library.
*
* @author Joe Smith jsmith@company.com
* @version 1.1
* @sdoc scripts/snazzyLib/ajax.sdoc
*/

@sdoc 은 현재의 자바스크립트 파일과 연결된 외부 scriptDoc 파일을 가리키며 절대/상대 경로가 모두 가능합니다.

클래스를 정의할 때에는 @classDescription, @memberOf, @constructor, @type, @method 등을 이용합니다.

@membefOf 는 어떤 함수가 특정 클래스의 멤버 임을 가리킵니다. javascript 의 특성상 외부에 함수를 지정하고 이를 클래스의 메소드로 링크할 수도 있기 때문에 이런 식의 표기가 생긴 것 같습니다.

@constructor 는 클래스의 생성자를 표시하고,
@type 은 프로퍼티의 객체 타입을 가리키며,
@exception 은 메소드에서 반환 가능한 예외를 표기합니다.
@method 는 함수가 어떤 클래스의 메소드인지 아닌지를 알려줍니다. 중괄호 안은 exception의 타입을 나타냅니다.

/**
* @memberOf fooBar
* @method
*/
function foo() {
....
}
함수나 메소드를 정의할 때는 위에서 가리킨 몇가지 외에도 @alias, @deprecated, @exception, @param, @return, @since 등이 가능합니다.

@alias 는 외부 scriptdoc 문서에서의 별명 링크를 지정합니다.
@param 은 함수의 파라미터로 사용되는 파라미터의 타입과 설명을 표기하고,
@deprecated 는 말 그대로 과거에는 구현되었으나 지금은 지원하지 않는(혹은 삭제예정인) 프로퍼티 혹은 메소드/함수를 가리킵니다.
@exception 은 메소드/함수에서 일어날 수 있는 예외를,
@return 은 반환값을 가리키며,
@since 는 이 프로퍼티/속성/메소드가 지원되기 시작한 버전을 표기합니다.

/**
* Sum two numbers
*
* @param {Number} Num1 integer to sum (first)
* @param {Number} Num2 integer to sum (second)
* @return {Number} Returns an result number
* @exception {ArgumentException} Throws a exception if number of argument is not two.
* @since 0.4
*/

function sum(Num1, Num2) {
return Num1 + Num2;
}
언어 자체가 자바보다는 단순한 만큼 항목이 많지 않아서 금방 적용해볼 수 있으며, 표준의 방식을 따름으로서 얻어지는 이점이라면(그렇다고 표준기구에서 제정된 것은 아닙니다), 관련된 IDE 나 프로그램 등에서 이를 이용한 지원을 받기가 더 용이하다는 점과 상호 규약을 지킴으로써 작업자간의 커뮤니케이션이 더 원활하다는 점이 있습니다.

아직 scriptDoc 을 문서로 만들어주는 도구는 없지만 조만간 나올 것이라고 봅니다. ^^ 이미 Aptana 같은 IDE 에서도 지원하기 시작했구요. 지금부터 써보는 습관을 들여도 좋을 것 같습니다.