코드 문서화란
코드 문서화는 코드의 사용법과 동작을 설명하는 것입니다. 40년간 문서화의 가치를 경험해온 저로서는 좋은 문서가 개발 생산성을 크게 높인다고 확신합니다. 코드에서 문서를 자동 생성하면 동기화 문제를 줄일 수 있습니다. 각 언어에 맞는 도구를 사용합니다.
JSDoc (JavaScript)
JSDoc은 JavaScript 코드의 주석에서 문서를 생성합니다. /* ... / 형식의 주석을 사용합니다. @param, @returns, @example 등의 태그를 지원합니다. TypeScript와도 함께 사용할 수 있습니다. HTML 문서를 생성합니다. 에디터 IntelliSense에도 활용됩니다.
Sphinx (Python)
Sphinx는 Python 프로젝트의 표준 문서화 도구입니다. reStructuredText로 작성합니다. autodoc으로 docstring에서 문서를 추출합니다. Read the Docs와 통합됩니다. HTML, PDF, ePub 등 다양한 형식으로 출력합니다. 대규모 프로젝트에 적합합니다.
Javadoc (Java)
Javadoc은 Java의 표준 문서화 도구입니다. Java 소스 코드의 특수 주석을 처리합니다. @param, @return, @throws 태그를 사용합니다. HTML 형식의 API 레퍼런스를 생성합니다. IDE에서 호버 시 표시됩니다. Kotlin에는 Dokka가 있습니다.
문서화 팁
공개 API는 반드시 문서화합니다. 복잡한 로직에는 설명을 추가합니다. 예제 코드를 포함합니다. 자동 빌드에 문서 생성을 포함합니다. 문서도 코드 리뷰 대상입니다. 너무 많거나 너무 적은 문서 모두 문제입니다. 적절한 균형을 찾습니다.
댓글
0