문서화의 과소평가된 가치
개발팀마다 다양한 상황과 가치가 존재하겠지만, 보통 문서화의 중요성을 과소평가하게 된다. 빠르게 이슈를 해결하고 프로젝트를 배포해야 한다면 더욱 문서화의 필요성은 낮은 우선순위로 여길 수밖에 없다. 이해한다. 하지만 가능하다면, 문서화를 개발 프로세스의 필수 불가결한 부분으로 생각할 수 있다면 좋지 않을까라고 생각한다. 그래서 나름의 대안으로 코드 내에 문서를 포함시키는 것이 중복을 방지하고 시간을 절약하며 문서화 프로세스를 더 간결하게 만들 수 있겠다. 실제로 그렇게 하는 팀들이 다수 있다고 본다.
문학적 프로그래밍
문학적 프로그래밍(Literate Programming)은 사람이 쉽게 이해할 수 있는 코드를 작성하는 것에 중점을 둔 프로그래밍 방법론이다. 기계가 컴파일 가능한 코드를 만드는 것보다. 이 방법론은 잘 구조화된 서술을 작성하는 것과 같은 방식으로 인간이 읽을 수 있는 문서를 만드는 프로그래밍 접근법을 지지한다. 이 방법론은 코드와 문서화 사이의 전통적인 이분법을 무시하고, 두 가지를 모델을 하나로 보며 직관적인 코드로 이해와 유지 보수를 높이려고 한다.
// Examples
/**
* This function calculates the factorial of a given number.
* @param n The number to calculate the factorial of.
* @returns The factorial of the given number.
*/
function factorial(n: number): number {
if (n === 0 || n === 1) {
return 1;
}
return n * factorial(n - 1);
}
/**
* This function calculates the sum of an array of numbers.
* @param numbers The array of numbers to sum.
* @returns The sum of the array of numbers.
*/
function sum(numbers: Array<number>): number {
return numbers.reduce((acc, curr) => acc + curr, 0);
}
// Example usage:
const numbers: Array<number> = [1, 2, 3, 4, 5];
console.log(sum(numbers)); // Output: 15
console.log(factorial(5)); // Output: 120내부와 외부 문서화
프로젝트는 보통 내부와 외부 두 종류의 문서가 존재한다. 내부 문서에는 소스 코드, 주석, 설계 및 테스트 문서가 포함되며, 외부 문서에는 사용자 매뉴얼과 같이 외부에 출판되는 모든 것이 포함된다. 이러한 분류는 필요하지만 장기적으로 관리 요소의 증가와 문서 간의 불일치의 내재적 위험을 내포하고 있을 수 있겠다.
처음부터 문서화 포함
가능하다면 문서화를 처음부터 전체의 일부로 통합하는 것이 어떨까. 나중에 추가하려고 시도하는 것은 여러모로 비용이 크게 든다. 코드는 무엇이 수행되고 있는지를 보여주고, 주석은 왜 그리고 어떻게 를 명확히 인지하는 데 도움을 준다.
코드 내 주석: 목적과 가이드라인의 논의
하지만 소스 코드 내의 주석은 공학적인 트레이드오프가 있을 수 있다. 분명한 것은 개발팀 내부적으로 필요성을 인식하고 논의 포인트들을 설정하며, 효과적인 작성 및 유지 관리 전략이 필요하다는 것이다.
주석은 코드의 이해를 돕고, 유지 보수를 쉽게 하며, 개발 팀 간의 소통을 향상시키는 중요한 요소라는 점에 공감이 필요하다. 이를 통해 결정의 근거와 버려진 대안들을 알게 하고, 다른 중요한 통찰에 도움을 주며, 프로젝트의 잠재적으로 간과된 부분을 문서화할 기회를 제공하게 된다.
다양한 주석 예제
1. 한 줄 주석 (Single-line Comments):
// 이 주석은 코드의 한 줄을 설명합니다.
int x = 5; // x 변수에 5를 할당합니다.
2. 다중 줄 주석 (Multi-line Comments):
/*
이 주석은
여러 줄에 걸쳐
코드를 설명합니다.
*/
int y = 10;
3. JavaDoc 주석 (JavaDoc Comments):
/**
* 이 메서드는 두 숫자의 합을 반환합니다.
*
* @author Dev-ooo
* @param a 첫 번째 숫자
* @param b 두 번째 숫자
* @return 두 숫자의 합
* @see Addition Util
*/
public int add(int a, int b) {
return a + b;
}
4. 태그를 사용한 주석 (Tagged Comments):
// TODO: 이 코드는 최적화가 필요합니다.
// FIXME: 이 부분에서 버그가 발생합니다.
int z = x + y;JavaDoc 주석은 메서드, 클래스, 또는 필드 위에 위치하며, 특정 태그(@param, @return 등)를 사용하여 추가 정보를 제공합니다. JavaDoc 은 이러한 주석을 사용하여 API 문서를 자동으로 생성할 수 있는 장점이 있다.
불분명한 설계 문서화의 불편함
때로는 소스 코드의 설계를 문서화하는 것이 불편하게 느껴지는데, 이는 작성한 코드의 설계가 불분명하기 때문일지도 모른다. 종종 코드의 최종 버전이 어떻게 될지 확실하지 않을 때도 이러한 불편함을 느낄 수 있다. 불확실성 속에서도, 코드의 현재 상태와 의도를 나타내려는 노력이 있다면, 이는 팀원들과의 코드의 현재 로직과 구조를 이해하고 프로젝트의 전반적인 방향성에 대해 논의할 수 있는 기회가 될 것이라는 기대도 해본다.
