
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 수년에 걸쳐 저는 온갖 종류의 프로젝트—크고, 작고, 혼란스럽고, 과도하게 설계되었고, "임시"이고, 명백히 잘 구조화된 것 등 모든 것을 다루어 왔습니다. 하지만 한 가지 패턴은 웃기게도 일관되었습니다. 문서는 항상 없거나, 오래되었거나, 2019년 타임스탬프에 의해 보호되는 Confluence의 잊혀진 구석에 묻혀 있습니다. 모든 프로젝트는 문서가 있다고 *주장합니다*. 모든 팀은 문서를 최신 상태로 유지할 것이라고 *약속합니다*. 그리고 모든 개발자는 자신 있게 말합니다. "걱정 마세요. 나중에 쓸게요." 이는 우리 모두 알고 있듯이, 문서의 "수표는 우편으로 보내졌어요"와 같은 말입니다. 이 주기가 제가 인정하고 싶지 않은 것보다 더 많이 반복되는 것을 지켜본 후, 저는 단순하지만 냉혹하게 진실된 것을 깨달았습니다. 
 
 문서는 코드에 최대한 가까이 있을 때만 살아남습니다. 개발자(저를 포함)는 게으른 존재이기 때문입니다. 그리고 그것으로부터 또 다른 깨달음이 왔습니다. 오래된 문서의 주요 문제는 대부분의 팀이 이를 주요 개발 주기에 포함시키지 않고, 나중으로 미루거나 이미 Confluence 어딘가에 가지고 있던 몇 가지 사전 개발 사양으로 만족한다는 사실입니다. 의미 있는 문서를 작성하기 위해 소프트웨어 구성 요소에 대한 문서 유형을 먼저 논의해 보겠습니다. 개발자가 실제로 사용할 수 있는 코드 문서화 방법 문서가 코드에 가까이 있어야 한다는 것을 받아들이면, 다음 질문은 *어떻게* 구조화할 것인가입니다. 실제로 좋은 문서는 단일 아티팩트가 아니라 다양한 목적과 대상을 serving하는 계층의 작은 생태계입니다. 제가 언급한 프로젝트(Java + Spring Boot로 작성됨)의 경우, 네 가지 주요 문서 유형을 식별했습니다. 1. 클라이언트 사양 이들은 일반적으로 도메인 전문가가 컴파일하는 일반적인 문서입니다. 이상적으로는 보편적인 언어로 풍부하고 비코드 관련 비즈니스 사례 설명을 제공합니다. 즉, 엔지니어가 당면한 문제를 진정으로 이해하는 데 필요한 모든 것입니다. 불행히도 현실에서는 이러한 문서가 종종 Confluence 어딘가에 저장되어 프로젝트 초기에 팀과 공유된 후 거의 다시 업데이트되지 않습니다. 오해하지 마세요. 이러한 문서는 *중요합니다*. 도메인 전문가로부터 지식을 추출하는 것은 모든 엔지니어링 팀의 최우선 과제가 되어야 합니다. 하지만 사양은 진화하고, 마감일은 모두를 스트레스 받게 하며, 원래 문서는 천천히 그리고 확실히 오래된 기반이 됩니다. 변경되는 요구 사항, 엣지 케이스 및 프로젝트 전환에 대한 지식은 코드 내에서—또는 더 나쁘게는—시니어 개발자의 머릿속에서 살아남게 됩니다. 이를 해결하기 위해 무작위 Word 파일이나 잊혀질 운명의 Confluence 페이지에 사양을 작성하는 것을 중단하고 이를 최전선에 최대한 가깝게 옮겼습니다:  코드 저장소. 저장소 내부에 docs/ 폴더에 Markdown(.md) 파일로 저장하기 시작했습니다. 대규모 마이크로서비스 환경에서는 이러한 문서가 Git 서브모듈로 연결된 전용 저장소를 정당화할 수도 있습니다. 서브모듈은 종종 간과되지만, 다중 저장소 생태계를 구성하는 강력한 방법입니다. 서브모듈에 대한 자세한 내용은 이 블로그 게시물을 강력히 추천합니다 -  . link 2. README – 사람을 위한 정문 클라이언트 사양이 백과사전이라면 README는 정문입니다. 하지만 소프트웨어 프로젝트에서 가장 간과되는 문서 중 하나입니다. 아이러니하게도 거의 모든 버전 제어 플랫폼—GitHub, GitLab, Bitbucket—은 저장소의 메인 페이지에서 README를 자동으로 렌더링합니다. 저장소에 처음 접속하는 모든 개발자가 가장 먼저 보는 것입니다. 그럼에도 불구하고 README는 종종 놀라울 정도로 비어 있거나, 고통스러울 정도로 오래되었거나, "TODO: 나중에 문서 작성"이라는 끔찍한 내용으로 채워져 있는데, 물론 이것은 결코 일어나지 않습니다. 좋은 README는 선택 사항이 아닙니다. *클릭이 전혀 필요하지 않기 때문에* 실제로 읽힐 가능성이 가장 높은 단일 문서입니다. 그리고 저장소의 루트에 있기 때문에 개발자는 코드를 작업하면서 업데이트할 가능성이 더 높습니다. 이것은 최소 저항 경로에 있는 문서입니다. 잘 쓰여진 README는 개발자가 프로젝트를 접한 후 몇 분 안에 갖게 되는 가장 중요한 질문에 답해야 합니다. 
 
 
 
 
 
 
  간결한 목적 및 컨텍스트 설명—마케팅 허용 없이. 이 서비스/프로젝트/구성 요소는 무엇을 합니까? -  런타임 지침, 환경 변수, 종속성 설정 및 프로젝트별 명령. 로컬에서 어떻게 실행합니까? -  단위 테스트, 통합 테스트, 테스트 데이터 설정 및 테스트 관련 도구. 어떻게 테스트합니까? -  디렉토리 레이아웃, 주요 모듈 및 코드의 중요한 부분을 어디에서 찾을 수 있는지에 대한 간략한 설명. 프로젝트는 어떻게 구성되어 있습니까? -  배포 스크립트, CI/CD 노트, 필요한 권한 또는 플랫폼 미묘한 차이. 어떻게 배포합니까?  생성된 문서, 아키텍처 노트, API 참조 및 중앙 집중식 디자인 문서 링크. 더 자세히 읽을 수 있는 곳은 어디입니까? - README는 프로젝트의 관문입니다. 기대치를 설정하고, 온보딩 시간을 줄이며, 새롭거나 숙련된 모든 엔지니어에게 명확한 방향을 제시합니다. 제대로 유지 관리되면 저장소 전체에서 가장 가치 있는 단일 문서가 됩니다. 3. JavaDocs – 컴파일러가 유지하도록 귀찮게 하는 문서 JavaDocs—일반적으로 보이지 않고, 종종 잊혀지지만, 무언가가 고장났을 때 절대적으로 필수적입니다. 실제로 Java 프로젝트를 문서화하는 것은 종종 두 가지 극단으로 나뉩니다: 모든 사소한 줄에 *과도하게 주석을 달거나*, "코드가 자체 설명적이기 때문에" *전혀 주석을 달지 않는 것*입니다. 진실은 언제나 그렇듯이 그 중간에 있습니다. 우리 프로젝트에서는 *정말로 필요한 것만* 문서화하기로 의식적인 결정을 내렸습니다. 그것은 다음을 의미했습니다. 
 
 
 
 
 비즈니스 사양과 정확히 일치하는 도메인 용어를 사용하기 위해 *보편적인 언어* 사용 코드가 이미 보여주는 *무엇*이 아니라, 명백하지 않은 결정 뒤에 있는 *왜*를 설명 핵심 도메인 클래스, 인터페이스 및 복잡한 워크플로우 문서화 메서드 이름을 장황하게 반복하는 주석 벽 피하기 JavaDocs는 올바르게 사용될 때 코드에 혼란을 주지 않으면서 의도를 명확히 하는 마이크로 수준의 문서 역할을 합니다. 그리고 Confluence 페이지와 달리 JavaDocs는 내장된 이점을 가지고 있습니다. 
 
 동기화가 벗어나면 컴파일러가 실제로 불평합니다. 매개변수를 이름 변경했지만 JavaDoc 태그를 잊어버리면 빌드가 이를 상기시켜 줍니다. 메서드를 삭제했지만 오래된 주석 참조를 남겨두면 IDE가 크리스마스 트리처럼 빛날 것입니다. 이러한 부드러운 마찰은 JavaDocs가 다른 형태의 문서보다 더 정확하게 유지되는 이유입니다. 이를 무시하는 것은 귀찮은 일입니다. 모든 것을 중앙 집중화하고 "문서 섬"을 피하기 위해 **Doxygen**도 사용했습니다. Doxygen은 소프트웨어 개발에서 널리 사용되는 문서 생성 도구입니다. 주로 C++ 커뮤니티에서 사용되지만, JavaDocs를 일관되고 탐색 가능한 참조(HTML 페이지)로 집계하는 데 사용했습니다. 계층 구조 및 협업 컨텍스트에 대한 클래스 다이어그램, 더 많은 요약 페이지 등 JavaDoc이 제공하지 않는 많은 기능을 제공합니다. 이를 통해 분산된 IDE 힌트에 의존하지 않고 코드베이스 전체의 깔끔하고 통합된 보기를 얻을 수 있었습니다. 4. 클린 코드 – 유지보수가 필요 없는 문서 마지막으로, 가장 과소평가된 형태의 문서는 개발자가 정말 필요할 때까지 가장 적게 존중하는 것입니다:  클린 코드. 주석은 오래됩니다. 사양은 벗어납니다. README는 무시됩니다. JavaDocs는 오래될 수 있습니다. 하지만 잘 쓰여진 코드—명확하고, 의도적이며, 표현적인 코드—는 *문서입니다*.  Uncle Bob이 유명하게 말했듯이,  "클린 코드는 잘 쓰여진 산문처럼 읽힙니다." 그리고 실제로는 다음과 같은 것을 의미합니다. 
 
 
 
 
 
 
 목적을 드러내는 이름의 클래스와 메서드 하나의 일을 잘하는 함수 도메인 용어를 일관되게 사용 이유 없는 영리함 없음 부작용 속에 숨겨진 불필요한 "놀라운 동작" 없음 박사 학위가 필요한 복잡한 추상화 없음 클린 코드는 리팩토링, 스프린트, 인력 교체 및 조직적 혼란을 견딜 수 있는 유일한 아티팩트입니다. 시스템의 동작과 항상 동기화되어 있기 때문에—*그것은 시스템의 동작 자체입니다*.  시간이 지남에 따라 간단한 규칙이 생겼습니다:  메서드를 설명하기 위해 한 단락의 주석이 필요하다면, 실제 문제는 메서드입니다. 코드가 표현적이면 다른 모든 것이 쉬워집니다 → JavaDocs는 더 가볍고 집중적으로 됩니다 → 온보딩이 명확해지므로 README가 축소됩니다 → 도메인 모델이 비즈니스 어휘를 반영하므로 사양이 더 명확해집니다. 클린 코드가 문서의 필요성을 제거하는 것은 아닙니다. 그것은 문서를 *고정*시킵니다. 사양, README, JavaDocs와 같은 다른 모든 형태의 문서가 불분명한 구현을 보완하는 대신 진실을 강화하도록 합니다. 결국 클린 코드는 유지보수, CI 통합 또는 도구가 필요 없는 문서입니다. 그것은 시스템이 실제로 하는 일에 대한 가장 정직하고 신뢰할 수 있는 설명입니다. 모두 함께 — 살아있는 문서 파이프라인 문서 작성 방식을 개선한 후 마지막 단계는 문서가 단순히 생성되는 것이 아니라 지속적으로 제공되고 항상 액세스 가능하도록 하는 것이었습니다. 이를 위해 사양, README 파일 및 JavaDocs를 단일 통합된 **살아있는 문서 포털**로 전환하는 문서 파이프라인을 구축했습니다. 문서를 코드에 최대한 가깝게 유지하고 싶었기 때문에 GitHub Pages를 통해 모든 것을 배포하기로 결정했습니다. GitHub Pages는 코드베이스에 직접 연결된 간편하고 버전 제어된 호스팅 솔루션을 제공합니다. GitHub Pages는 GitHub에만 국한되지 않습니다 (예: GitLab에도 GitLab Pages가 있습니다). 인기 있는 버전 제어 시스템의 또 다른 훌륭한 기능이며 추가 읽기를 권장합니다 -  . link 모든 것을 응집력 있는 페이지 세트로 컴파일하기 위해 **Sphinx**를 사용했습니다. Sphinx는 Python으로 작성된 강력한 문서 생성기입니다. reStructuredText 또는 Markdown으로 작성된 소스 파일을 HTML, PDF 및 ePub을 포함한 다양한 출력 형식으로 변환합니다. Sphinx는 구조, 탐색 및 테마를 처리했습니다. Doxygen은   플러그인을 사용하여 자동 생성된 JavaDocs를 Sphinx에 공급하여 소스 코드에서 직접 완전히 탐색 가능한 API 참조를 제공했습니다. 한편, 루트 README는 저장소를 탐색하는 개발자를 위한 즉각적인 진입점 역할을 했으며, 생성된 문서 사이트로 원활하게 연결되었습니다. Breathe main으로의 모든 병합은 문서의 재빌드를 트리거하는 CI 작업을 실행하여 포털이 최신 코드 변경 사항, API 업데이트 및 디자인 결정을 반영하도록 했습니다. 고립된 것은 아무것도 없었습니다. 수동 동기화가 필요한 것은 없었습니다. 그리고 결정적으로—하나의 클릭 이상이 필요한 것은 없었습니다. 이를 통해 문서를 정적 아티팩트에서 개발자가 실제로 사용하는 지속적으로 업데이트되는 생태계로 전환했습니다. 왜냐하면 개발자의 일상 작업 흐름에 직접 통합되고 코드 바로 옆에 있었기 때문입니다. 결론 — 문서는 우리의 책임이지 부담이 아닙니다 결국 문서를 작성하는 것은 선택 사항이 아닙니다. 엔지니어링 전문가로서 우리의 직무의 일부입니다. 미래 팀원들이 이에 의존합니다. 온보딩이 이에 의존합니다. 유지보수, 신뢰성, 심지어 아키텍처의 명확성까지 이에 의존합니다. 하지만 그 책임을 받아들인다고 해서 문서가 고통스러워야 한다는 의미는 아닙니다. 문서를 코드에 가깝게 유지하고, 자동화할 수 있는 것은 자동화하고, Markdown, JavaDocs, Doxygen, Sphinx와 같은 스마트한 도구에 의존함으로써, 우리는 일반적으로 문서 노력을 망치는 마찰을 제거합니다. 우리는 전통적으로 귀찮은 일처럼 느껴지는 것을 일상적인 개발의 자연스러운 확장으로 전환합니다. 그리고 클린 코드, 좋은 README, 도메인 풍부한 사양과 쌍을 이루면 전체 생태계가 자급자족하게 됩니다. 문서가 완벽할 필요는 없습니다—단지 접근 가능하고, 정확하며, 살아있으면 됩니다. 개발자가 코드를 작성하는 것처럼 쉽게 문서를 업데이트하도록 장려하는 시스템을 구축하면 팀, 제품, 그리고 무엇보다도 6개월 후에 프로젝트를 인계받는 불쌍한 영혼까지 모두가 혜택을 받습니다. 좋은 문서는 우리를 덜 게으르게 만들지 않습니다. 그것은 단지 게으른 것을 훌륭한 소프트웨어를 구축하는 것과 양립 가능하게 만들 뿐입니다.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Read My Stories

이 오디오는 이야기의 원래 언어로 제작되었습니다!

문서가 열리는 데 두 번의 클릭이 걸린다면 축하드립니다. 이미 오래된 것입니다.

About Author

코멘트

태그 걸기

이 기사는 다음에서 발표되었습니다.

Related Stories

성공적인 클라우드 마이그레이션을 위한 전체 가이드: 전략 및 모범 사례

Floki의 Valhalla가 인도 스리랑카 투어의 보조 후원자로 합류

작업 흐름을 10배 향상하는 방법: 17가지 필수 앱

AI의 힘을 발휘하세요. 최첨단 기술의 체계적 검토: 개요 및 소개

성공적인 클라우드 마이그레이션을 위한 전체 가이드: 전략 및 모범 사례

Floki의 Valhalla가 인도 스리랑카 투어의 보조 후원자로 합류

작업 흐름을 10배 향상하는 방법: 17가지 필수 앱

AI의 힘을 발휘하세요. 최첨단 기술의 체계적 검토: 개요 및 소개

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps