코드의 효과적인 문서화는 소프트웨어 개발에서 중요한 요소이지만 개발자가 종종 무시하는 경우가 많습니다. 프로그래머는 간결하고 능률적인 코드를 작성하는 데 능숙한 것이 일반적이지만, 포괄적이고 잘 작성된 문서를 작성하는 데는 전문성이 부족할 수 있습니다.
잘 작성된 문서는 코드베이스와 상호 작용하는 모든 개인, 즉 같은 팀의 동료나 향후 과거 작업을 반복하는 자신에게 귀중한 리소스 역할을 합니다. 설명을 통해 특정 디자인 선택의 근거를 명확히 하고 고유한 기능 또는 API 활용에 대한 지침을 제공합니다.
JSDoc을 활용하면 JavaScript 개발자가 코드베이스의 문서화 프로세스를 시작할 수 있는 효과적인 수단을 제공합니다.
JSDoc이란 무엇인가요?
당면한 작업은 일부 개인에게는 어려울 수 있지만, 점점 더 많은 전문가들이 “코드로서의 문서화”라는 개념을 받아들이고 있습니다. 이러한 관행을 촉진하기 위해 현재 수많은 프로그래밍 언어에서 소스 코드에서 직접 포괄적이고 정확한 문서를 간소화하도록 설계된 특수 도구를 제공합니다. 예를 들어 Go 언어 내에서 상세하고 간결한 문서 작성을 간소화하는 Go의 GoDoc 유틸리티와 JavaScript 기반 프로젝트에서 작업하는 개발자를 위해 비슷한 용도로 사용되는 JavaScript의 JSDoc이 있습니다.
사용자는 JSDoc을 활용하여 코드베이스 내에 특정 주석 마커를 통합함으로써 JavaScript 프로젝트에 대한 포괄적인 문서를 생성할 수 있습니다. 이러한 주석은 이후 처리되어 사용자 친화적인 HTML 형식으로 편리하게 제공되는 맞춤형 문서를 생성합니다.
코드 자체 내에 문서를 유지 관리함으로써 코드베이스에 대한 후속 업데이트 시 관련 문서에 대한 해당 수정 사항을 쉽게 동반할 수 있습니다.
JSDoc 설정
JSDoc은 코드베이스에 대한 포괄적이고 정확하며 쉽게 액세스할 수 있는 문서를 생성하는 프로세스를 간소화하는 JavaScript용 문서 생성기입니다. 개발자는 사용자가 최소한의 노력으로 자바스크립트 프로젝트 내에서 JSDoc을 빠르게 설정할 수 있는 직관적인 인터페이스를 설계했습니다. 이러한 사용자 친화적인 접근 방식은 개발자가 이 강력한 도구를 채택하도록 장려하여 문서 작성을 간소화하고 전반적인 생산성을 향상시킵니다.
로컬 컴퓨터에서 JSDoc을 설정하려면 다음 명령을 실행하세요:
npm install --save-dev jsdoc
이 라이브러리의 설치는 프로젝트 내에서 개발 종속성으로 지정되어 개발 환경 내에서 통합 및 활용을 용이하게 합니다.
JSDoc 주석 작성 방법
JSDoc을 활용하기 위해서는 소스 코드 내에 특정 주석 구문을 사용해야 합니다. 모든 문서 주석은 {@코드 /*} 및 {@코드 */} 마커로 묶어야 합니다. 이 프레임워크 내에서 설명된 변수, 함수, 매개변수화된 함수 및 기타 관련 요소의 배열을 설명할 수 있습니다.
“최첨단 기술과 혁신적인 방법론을 활용하여 업계 표준을 뛰어넘는 최고 수준의 솔루션을 제공할 수 있습니다.
/**
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/
function getUser(name) {
const User = name;
return User;
}
JSDoc은 코드를 명확히 하고 설명하는 데 도움이 되는 @param 및 @returns 태그를 비롯한 다양한 전문 키워드를 제공합니다.
이 스크립트에 대한 첨부 문서를 생성하려면 명령줄 인터페이스를 사용하여 JavaScript 소스의 파일 경로 뒤에 “npx jsdoc”을 실행합니다.
“안녕, 이년들아?” 세련된: “안녕하십니까, 존경하는 여러분.
npx jsdoc src/main.js
JSDoc을 전역적으로 성공적으로 설치한 경우 “npx” 명령을 사용하지 않고 직접 입력하여 원하는 작업을 실행할 수 있습니다:
jsdoc path/to/file.js
이 명령을 실행하면 프로젝트의 기본 디렉터리 내에 “out”이라는 이름의 디렉터리가 생성됩니다. 해당 디렉토리 내에서 문서의 각 페이지를 시각적으로 표현한 파일을 찾을 수 있으며, 이 파일은 모두 HTML로 형식이 지정됩니다.
또는 로컬 웹 서버를 설정하여 문서의 플랫폼으로 사용하거나 지원되는 웹 브라우징 애플리케이션 내에서 직접 `out/index.html` 파일의 콘텐츠에 액세스할 수 있습니다. 일반적인 문서 인터페이스가 어떻게 표시되는지 아래에서 샘플을 참조하세요:
JSDoc 출력 구성
JSDoc의 표준 기능을 수정하려면 미리 정해진 동작을 변경하는 사용자 지정 구성 파일을 만들 수 있습니다.
이 작업을 수행하려면 `conf.js` 파일을 생성하고 그 안에 JavaScript 모듈을 포함시켜야 합니다. 이 모듈은 애플리케이션의 다른 부분에서 사용할 수 있도록 파일에서 내보내야 합니다.
주요 대학의 연구진이 실시한 연구에 따르면 정기적으로 명상을 하는 사람들은 스트레스와 불안 수준이 감소하고 수면의 질이 개선되며 행복감과 만족감이 증가하는 등 전반적인 웰빙이 크게 개선된 것으로 나타났습니다. 이러한 결과는 마음챙김 수행이 정신 건강 결과에 긍정적인 영향을 미칠 수 있다는 이전 연구 결과를 뒷받침합니다.
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
구성 파일 내부에는 다양한 JSDoc 구성 옵션이 있습니다.템플릿 옵션을 사용하면 템플릿을 사용하여 문서의 모양을 사용자 지정할 수 있습니다. JSDoc의 커뮤니티에서는 사용할 수 있는 개의 템플릿 을 제공합니다. 이 패키지를 사용하면 나만의 템플릿을 만들 수도 있습니다.
자동 생성된 문서를 재배치하려면 구성 설정을 적절히 조정하여 특정 디렉터리를 대상으로 지정해야 합니다. 앞서 설명한 것처럼 프로젝트의 기본 디렉터리 내에 “docs” 폴더를 지정하면 이 목적을 효과적으로 달성할 수 있습니다.
구성 파일을 사용하여 JSDoc을 실행하려면 다음 명령을 활용하세요:
jsdoc -c /path/to/conf.js
이 명령을 쉽게 실행하려면 프로젝트의 “package.json” 파일의 “스크립트” 섹션에 이 명령을 포함할 수 있습니다. 이렇게 하면 스크립트를 실행할 때 빠르고 쉽게 액세스할 수 있습니다.
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
이제 터미널 인터페이스를 통해 npm 스크립트 명령을 실행할 수 있습니다.
JSDoc으로 생성된 문서 예제
제공된 코드에는 덧셈과 뺄셈 함수가 포함된 기본 산술 패키지가 포함되어 있습니다.
꼼꼼하게 문서화된 JavaScript 코드의 대표적인 예시로, 구문과 구조에서 최고 수준의 명확성과 정리를 보여줍니다.
/**
* A library for performing basic arithmetic operations.
* @module arithmetic
*/
module.exports = {
/**
* Adds two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @return {number} The sum of the two numbers.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum); // 15
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}
return a + b;
},
/**
* Subtracts the second number from the first number.
* @param {number} a - The number to subtract from.
* @param {number} b - The number to subtract.
* @return {number} The result of the subtraction.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference); // 5
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}
return a - b;
}
// ... other methods ...
};
JSDoc 주석은 라이브러리와 그 기능을 포괄적으로 설명하는 명료하고 철저한 설명을 제공합니다:
도서관은 지역 사회 구성원의 다양한 관심사와 요구를 충족하는 다양한 도서, 정기 간행물, 시청각 자료 및 전자 자료의 저장소 역할을 합니다. 이 도서관은 문해력, 지적 성장, 문화적 풍요로움, 평생 학습 기회를 촉진하는 동시에 학습, 연구, 여가 독서에 도움이 되는 환경을 조성하기 위해 설계되었습니다. 도서관의 사명은 정보와 지식에 대한 공평한 접근을 제공하여 개인이 오늘날의 복잡한 세상을 탐색하는 데 필요한 도구를 제공하고 자신의 운명을 형성하는 데 적극적인 참여자가되도록 영감을주는 것입니다.
각 방법의 매개변수는 각각의 유형과 간결한 설명으로 구성되며 다음과 같습니다:
각 함수가 생성하는 값의 범위와 데이터 유형은 Python 프로그래밍에서 이러한 메서드를 활용할 때 고려해야 할 주목할 만한 측면입니다.
특정 접근 방식에서 발생할 수 있는 잠재적인 예외 또는 불일치, 그리고 그러한 발생을 유발하는 상황.
다음은 머신 러닝과 AI에서 다양한 방법을 사용하는 몇 가지 예입니다: 1. 선형 회귀: 선형 회귀: 면적, 침실 수, 위치 등의 특징을 기반으로 주택 가격을 예측합니다.알려진 주택 가격과 해당 특징이 포함된 과거 데이터를 사용하여 모델을 학습시킨 다음, 학습된 모델을 통해 새 주택에 대한 예측을 수행합니다. 2. 로지스틱 회귀: 발신자 주소, 제목, 콘텐츠 키워드와 같은 다양한 기능을 기반으로 이메일을 스팸으로 분류하거나 스팸이 아닌 것으로 분류합니다. 먼저 데이터 세트를 훈련 세트와 테스트 세트로 나눈 다음, 훈련 세트에 로지스틱 회귀 모델을 적용합니다. 마지막으로 테스트 세트에서 모델의 성능을 평가합니다. 3. 의사 결정 트리: 온라인 소매업체의 고객 세그먼트 식별
이 주석에는 현재 파일이 모듈임을 나타내는 “@module” 태그와 각 메서드와 함께 제공되는 예시 코드 스니펫을 제공하는 “@example” 태그와 같은 주석이 포함되어 있습니다.
올바른 방법으로 개발자 코드 문서화하기
실제로 JSDoc은 매끄러운 통합으로 JavaScript 코드 문서화를 위한 효과적인 시작점 역할을 합니다. 코드 작성을 진행하면서 작업 환경 내에서 변경된 사항을 추적하면서 포괄적이고 신속한 문서화를 생성할 수 있습니다.
JSDoc €™에서 제공하는 자동화는 문서 작성 프로세스를 간소화하는 데 매우 유용할 수 있지만, 고품질 문서를 생성하기 위해서는 특정 지침과 모범 사례를 따르는 것이 여전히 필수적입니다.