코드 문서화란 무엇인가요?| IBM

코드 문서화의 정의

코드 문서화는 소프트웨어 프로젝트의 소스 코드를 설명하고 설명하는 프로세스입니다. 이는 소프트웨어 개발의 필수적인 부분이며 코드 주석, 공유 파일 또는 중앙 지식 베이스 등 다양한 형태를 취할 수 있습니다.

코드 문서는 코드베이스와 상호작용하는 사람들을 위한 지도 역할을 하며, 각 코드 조각이 무엇을 하는지, 어떻게 작동하는지, 어떻게 사용하는지, 모든 코드 조각이 어떻게 서로 연결되는지 탐색하는 데 도움이 됩니다. 코드 문서화는 개발 팀이 소스 코드를 더 잘 관리하는 데 도움을 주며, 사이버 보안 분석가, 데이터 과학자, DevOps 엔지니어, 제품 및 프로젝트 관리자, QA 엔지니어, 기술 작가 등 코드를 이해하고 다뤄야 할 다른 이해관계자들을 안내하는 역할도 합니다.

코드 문서화와 코드로서의 문서 비교

코드로서의 문서("docs as code")는 문서를 소프트웨어 코드처럼 취급합니다. 이 접근법은 소스 코드와 동일한 도구를 사용하여 문서를 관리하며, 변경 사항을 검토하고 추적하는 버전 관리 시스템, 서식 및 스타일 문제를 식별하는 자동 테스트, 문서 업데이트 및 배포를 위한 지속적 통합/지속적 배포(CI/CD) 등을 포함합니다.

코드 문서화는 코드를 문서화하는 광범위한 관행을 포함하지만, 코드로서의 문서는 문서 작성에 대한 구체적인 전략이자 보다 기술적인 접근 방식입니다.

코드 문서화의 유형

코드 문서의 구조는 대상이 누구이며 어떻게 사용되는지에 따라 달라집니다. 다음은 몇 가지 일반적인 문서 유형입니다.

저수준 문서
고수준 문서
내부 문서
외부 문서

저수준 문서

저수준 문서는 일반적으로 코드 내의 인라인 주석을 참조합니다. 문서를 작성하는 가장 기본적인 방법 중 하나인 이러한 주석은 특정 코드 줄이나 블록을 설명합니다.

def multiply(x, y):
# Returns the product of two numbers
return x * y

문서 문자열(docstring)은 또 다른 저수준 문서화 기법입니다. 문서 문자열은 클래스, 함수, 메서드 또는 모듈 정의 앞에 표시됩니다. 문서 문자열에는 목적, 사용 예, 기능, 매개변수 및 반환값을 선언하는 구조화된 형식이 있습니다.

def reverse_string(s):
‘’’
Returns the reverse of a string value
Parameters:
s (str): The string to be reversed
Returns:
rev (str): The string value in reverse
‘’’

rev = ‘’
x = len(s)

while x > 0:
rev += s[x - 1]
x = x - 1

return rev

인라인 주석은 코드 자체를 검사하여 얻을 수 없거나 더 복잡한 알고리즘을 기반으로 하는 코드에서 로직을 얻을 수 없는 경우 로직을 지정하는 데 더 적합합니다. 한편, docstring은 애플리케이션 프로그래밍 인터페이스(API) 문서에서 추출할 수 있으며, 통합 개발 환경(IDE) 내에서 상황에 맞는 도움말을 제공할 수 있습니다.

고수준 문서

코드의 각 부분을 개별적인 요소로 설명하는 저수준 문서와 달리, 고수준 문서는 더 넓은 아키텍처 워크플로에서 해당 요소의 역할에 대한 세부 정보를 포함합니다. 이 유형의 소프트웨어 문서에는 코드 아키텍처를 설명하는 순서도와 통합 모델링 언어(UML) 다이어그램, 비즈니스 로직과 코드가 제품 요구 사항에 맞게 조정되는 방식을 설명하는 설계 문서, 코드베이스 또는 코드 리포지토리의 구조 사양이 포함됩니다.

내부 문서

이 기술 문서는 기업 내부용입니다. 예로는 코딩 규칙과 표준 및 팀이 소프트웨어를 구축하는 방법에 대한 프로세스 문서가 있습니다. 개발 환경 설정 가이드도 내부 문서에 해당합니다.

외부 문서

이 사용자 대상 문서는 개발자와 기업 외부의 다른 사용자를 대상으로 합니다. 예를 들어, API 문서는 소프트웨어 프로젝트의 공개 API에서 사용 가능한 클래스, 함수, 메서드 및 모듈을 설명합니다. 또한 외부 문서는 구성 파일, 통합 노트, README 파일로 구성될 수 있습니다.

README 파일은 일반 텍스트 형식을 지정하기 위한 경량 마크업 언어인 markdown으로 작성됩니다. 여기에는 프로젝트 기능, 종속성, 설치 지침, 명령줄 인터페이스(CLI) 명령 및 도움말 및 지원을 받기 위한 옵션에 대한 정보가 포함되어 있습니다. 오픈 소스 프로젝트는 또한 버그 수정 또는 코드 변경 사항을 코드 리포지토리의 기본 분기에 병합하기 위해 풀 요청을 제출하기 위한 라이선스 세부 정보 및 기여자 지침을 추가합니다.

전문가의 인사이트를 바탕으로 한 최신 기술 뉴스

Think 뉴스레터를 통해 AI, 자동화, 데이터 등 가장 중요하고 흥미로운 업계 동향에 대한 최신 소식을 받아보세요. IBM 개인정보 보호정책을 참조하세요.

코드 문서화의 이점

깔끔하고 명확한 방식으로 코드를 작성하는 것은 그 자체로 문서 형식이 될 수 있습니다. 그러나 좋은 문서화는 여전히 필수적이며, 다음과 같은 이점을 제공합니다.

협업 강화

유지 관리 가능성 향상

소프트웨어 개발 가속화

온보딩 간소화

협업 강화

잘 문서화된 코드는 개발팀 내 협업과 커뮤니케이션을 원활하게 합니다. 구성원은 코드 검토를 수행하고, 코드 변경을 논의하고, 팀으로서 의사 결정을 내리기 위한 공유 언어로 코드 문서를 활용할 수 있습니다.

유지 관리 가능성 향상

문서화는 코드 리팩터링, 유지 관리 및 성능 최적화를 용이하게 합니다. 디버깅 과정에서 개발자는 코드 문서를 참고 자료로 활용하여 코딩 오류를 찾아내고 그 근본 원인을 파악할 수 있습니다.

소프트웨어 개발 속도 향상

훌륭한 문서화는 신속한 개발을 위한 토대를 마련하여 코드 기능 파악에 소요되는 시간을 절약하고, 대신 적절한 코드 업데이트 적용에 집중할 수 있게 해 줍니다. 또한 변경 사항을 추적하는 데 도움이 되어 팀이 자주 변경되는 코드베이스에 발맞춰 나갈 수 있도록 합니다.

온보딩 간소화

코드 문서화는 새로운 팀원이 코드베이스의 내부 작동 방식을 학습하는 데 도움이 됩니다. 새로운 팀원은 코드의 디자인과 구조에 더 빨리 익숙해져서 프로젝트에 빠르게 기여할 수 있습니다.

효과적인 코드 문서화 작성을 위한 팁

코드와 문서는 함께 작동하므로 함께 발전해야 합니다. 또한 코드 작성에 대한 일부 지침은 문서 작성에도 동일하게 적용됩니다. 다음은 도움이 될 만한 팁입니다.

코드 문서화 표준 수립

문서와 코딩 통합

명확성과 간결성이 핵심

문서 코딩에 관한 의사 결정

계속 업데이트

코드 문서화 표준 수립

코딩 규칙과 마찬가지로 코드 문서화도 표준을 따라야 합니다. 이러한 표준에는 저수준 문서의 들여쓰기, 줄 바꿈 및 간격과 같은 일관된 형식이 포함됩니다. 한편, 템플릿 및 코드 문서화 도구는 API 문서 및 기타 고급 및 외부 문서의 스타일과 구조에 도움이 될 수 있습니다.

문서화와 코딩 통합

이에는 함수 완료 시 문서 문자열을 추가하거나, 복잡한 알고리즘이나 논리를 구현하면서 인라인 주석을 삽입하는 작업이 포함될 수 있습니다. 프로그래밍하는 동안 문서를 작성하면 개발자가 사고 과정과 의사 결정을 명확하게 표현할 수 있으므로 중요한 세부 사항이 손실되지 않도록 할 수 있습니다. 처음에는 시간이 더 걸릴 수 있지만, 코딩 프로세스의 자연스러운 일부가 되어 향후 디버깅, 최적화 및 리팩터링을 빠르게 진행할 수 있습니다.

명확성과 간결성이 핵심

과도한 문서화는 코드 가독성을 저해할 수 있습니다. 개발자는 깨끗하고 명확한 코드를 작성하는 것을 우선시한 다음 해당 코드와 함께 깔끔하게 맞는 필요한 문서를 추가해야 합니다.

간결함에 있어서는 적절한 균형을 찾는 것이 중요합니다. 예를 들어 짧고 간단한 코드 조각에는 문서가 전혀 필요하지 않을 수 있습니다. 반면, 보다 정교한 알고리즘의 경우 다양한 수준의 경험을 가진 개발자가 이해할 수 있는 방식으로 기본 논리를 설명하는 문서가 필요합니다.

문서 코딩에 관한 의사 결정

여기에는 설계, 아키텍처, 논리 및 알고리즘 선택이 포함됩니다. 높은 수준의 내부 문서나 공유 지식 기반을 통해 이러한 코딩 결정을 문서화하면 향후 변경 사항에 대한 컨텍스트를 제공할 수 있습니다.

계속 업데이트

개발 팀은 코드 문서화가 소프트웨어의 현재 상태를 반영하여 정확하고 완전하며 관련성이 있는지 확인하기 위해 코드 문서화를 정기적으로 검토하고 업데이트해야 합니다. 문서를 코드 검토 프로세스에 통합하면 정기 업데이트에 도움이 될 수 있습니다.

애플리케이션 개발

시작하기: 클라우드에서 기업용 애플리케이션 개발

이 영상에서 Peter Haumer 박사는 IBM Z Open Editor, IBM Wazi 및 Zowe 등 다양한 구성 요소와 사례를 시연하며 오늘날 하이브리드 클라우드에서의 최신 기업용 애플리케이션 개발이 어떤 모습인지 설명합니다.

클라우드 애플리케이션 개발 살펴보기

코드 문서화 도구

대부분의 IDE에는 코드 문서화 생성을 위한 확장 또는 플러그인이 있지만, 다른 프레임워크와 도구도 프로세스 자동화를 지원할 수 있습니다. 다음은 몇 가지 일반적인 문서 생성기입니다.

Doxygen

GitBook

Javadoc

JSDoc

Sphinx

Doxygen

Doxygen은 C, C++, Java, PHP, Python 등 여러 프로그래밍 언어를 지원합니다. 마크다운 렌더링이 가능하며 HTML, PDF 및 XML 형식으로 문서를 생성할 수 있습니다. Doxygen은 구성 파일을 통해 사용자 지정할 수 있으며, 클래스와 함수 간의 시각적 계층 구조와 상관 관계를 나타내는 다이어그램을 생성하는 기능을 제공합니다.

GitBook

GitBook은 웹사이트 형식으로 문서를 작성하고 게시할 수 있는 사용자 인터페이스를 제공하여 내외부 문서를 더욱 효율적으로 작성할 수 있도록 지원합니다. 이 플랫폼은 또한 GitHub 또는 GitLab 리포지토리와의 동기화 기능을 제공합니다.

Javadoc

Javadoc 툴은 Java 소스 코드 내의 문서 주석을 파싱하여 HTML 형식의 API 문서를 생성합니다. 클래스, 생성자, 필드, 인터페이스 및 메서드를 문서화할 수 있습니다.

JSDoc

Javadoc과 마찬가지로 JSDoc은 JavaScript 프로젝트용 API 문서를 생성합니다. JSDoc 오픈 소스 커뮤니티는 문서 맞춤 설정을 위한 템플릿과 도구를 개발했습니다.

Sphinx

Sphinx는 주로 Python용으로 개발되었지만, 다른 프로그래밍 언어로도 확장할 수 있습니다. 이 툴은 마크다운과 reStructuredText라는 자체 마크업 언어를 지원합니다. Sphinx는 다양한 아웃풋 형식으로 문서를 작성할 수 있으며, 다른 코드 요소에 연결하는 상호 참조 기능을 제공합니다.

코드 문서화를 위한 생성형 AI

문서 생성기는 소스 코드 전체에서 접하는 주석으로 제한됩니다. 생성형 AI는 특정 코드 스니펫을 분석하고 목적과 기능을 설명하는 코드 주석을 추가하여 문서화를 한 단계 더 발전시킵니다. 대다수의 코드용 대규모 언어 모델(LLM)에는 문서 생성 기능이 내장되어 있습니다.

예를 들어, IBM Bob은 단일 메서드 또는 클래스 내 모든 메서드에 대한 설명 줄을 생성할 수 있습니다. 기타 유사한 도구로는 GitHub Copilot, JetBrains AI Assistant, Mintlify 및 Tabine이 있습니다.

다른 인공 지능 시스템과 마찬가지로 개발자는 여전히 AI 기반 코드 문서화 도구의 아웃풋의 완전성과 정확성을 검토해야 합니다.

작성자

Rina Diane Caballar

Staff Writer

IBM Think

Cole Stryker

Staff Editor, AI Models