▲

GN⁺: "Architecture.md (2021)" 기술명세서

 (matklad.github.io)
1P by neo 9달전 | favorite | 댓글 1개

ARCHITECTURE.md 작성 권장

  • 오픈소스 프로젝트 유지 관리자에게 README와 CONTRIBUTING 옆에 ARCHITECTURE 문서를 추가할 것을 강력히 권장함.
  • 이 문서는 프로젝트의 고수준 아키텍처를 설명하며, 반복적인 기여자가 읽어야 하므로 짧게 유지하는 것이 좋음.
  • ARCHITECTURE 문서는 자주 변경되지 않을 내용만 포함해야 하며, 코드와 동기화를 시도하기보다는 연간 몇 번 검토하는 것이 바람직함.

문서의 목적과 중요성

  • 프로젝트에 대한 물리적 아키텍처에 대한 지식이 일반 기여자와 핵심 개발자를 구분하는 가장 큰 차이점임.
  • 프로젝트에 익숙하지 않은 경우 패치를 작성하는 데 2배 더 많은 시간이 걸리고, 코드를 변경해야 할 위치를 파악하는 데는 10배 더 많은 시간이 소요됨.
  • ARCHITECTURE 파일은 이러한 격차를 해소하는 데 효과적인 방법으로, 프로젝트의 구조에 대한 반성의 기회도 제공함.

문서의 구성

  • 문제에 대한 새로운 관점에서의 개요로 시작하고, 모듈 간의 관계를 설명하는 상세한 _코드맵_을 제공해야 함.
  • 중요한 파일, 모듈, 타입을 명시하되, 직접 링크하는 대신 이름으로 검색하도록 독려하여 유지 관리가 필요 없게 함.
  • 아키텍처 불변성을 명시적으로 지적하고, 계층 간의 경계를 지적해야 함.

건축적 불변성과 경계

  • 중요한 불변성은 종종 무언가의 부재로 표현되며, 코드를 읽는 것만으로 이를 파악하기 어려움.
  • 계층이나 시스템 간의 경계는 시스템의 구현에 대한 정보를 암시적으로 포함하고 있으며, 가능한 모든 구현을 제약함.

종단 간 관심사

  • 코드맵을 완성한 후, 종단 간 관심사에 대한 별도의 섹션을 추가해야 함.
  • ARCHITECTURE 문서의 좋은 예로 rust-analyzer의 architecture.md가 있음.

GN⁺의 의견:

  • ARCHITECTURE 문서는 프로젝트의 이해를 돕고, 새로운 기여자가 빠르게 코드 베이스에 익숙해지는 데 중요한 역할을 함.
  • 이 문서는 프로젝트의 구조를 명확히 하고, 중요한 아키텍처 원칙과 경계를 강조하여 개발자들이 시스템을 더 잘 이해하도록 돕는다.
  • 오픈소스 커뮤니티에서 ARCHITECTURE 문서의 채택은 프로젝트의 지속 가능한 성장과 유지 관리에 기여할 수 있으며, 이는 개발자들에게 매우 유익하고 흥미로운 접근 방식임.
▲
neo 9달전  [-]
Hacker News 의견

  • 오픈소스 프로젝트를 관리하고 코드 라인이 10k-200k 사이라면 ARCHITECTURE 문서를 추가하는 것을 강력히 권장합니다.

    • 아이디어는 좋지만, 저장소 크기에 상관없이 Readme에 아키텍처를 포함시킬 수 있다고 생각함. 예를 들어, 모든 사용자가 워크플로우를 이해할 수 있도록 주 Readme에 Mermaid 시퀀스 다이어그램을 의도적으로 배치함.

  • 이 접근법은 ad hoc 기여자가 많은 오픈소스 프로젝트에 대해 유지보수가 적은 모델로 훌륭함. 전담 엔지니어가 있는 프로젝트의 경우 ADRs를 고려해야 함. 이는 더 많은 유지보수를 필요로 하지만, "왜"와 "고려된 대안"을 기록하여 재구축 시 매우 도움이 됨.

  • 몇 년 전에 내 큰 부수적 프로젝트 중 하나에서 비슷한 것을 실험해봄:

    • 각 파일의 상단에 다른 ARCHITECTURE.md 파일로의 링크 트리가 있었음.

  • 모든 IDE는 표준 디렉토리 트리로 프로젝트의 폴더 구조를 왼쪽에 보여줌. 의존성 그래프로 프로젝트를 탐색하는 것을 지원하는 IDE가 있을까?

  • 여기서 작가가 쓴 것을 일반 소프트웨어 프로젝트로 확대 적용하는 것에 주의해야 함. 많은 기여자가 적은 맥락을 가진 큰 오픈소스 프로젝트에서는 이런 문서를 유지하는 것이 가치가 있음. 하지만 작은 작업 프로젝트에서 본 모든 개발자가 작성한 문서는 결국 관리되지 않게 됨.

  • 문서가 짧을수록 미래의 변경에 의해 무효화될 가능성이 낮아짐. 이것이 ARCHITECTURE 문서의 주된 규칙임 — 자주 변경될 가능성이 낮은 것들만 명시하라. 코드와 동기화하려고 시도하지 마라.

    • 인터페이스는 변경하기 덜 가능하고 [더 어렵다!] (Parnas, 시스템을 모듈로 분해하는 데 사용되는 기준).

  • 모든 프로젝트에서 온보딩 시 아키텍처 다이어그램과 그 구성 요소에 대한 간단한 설명을 보여줌.

    • 이제 오픈소스에서 이것이 얼마나 드문지 놀람.

  • 이것은 매우 유용한 관행임. 많은 프로젝트에는 대부분의 변경이 일어나는 몇 개의 핵심 파일(또는 패키지/모듈/등)이 있음. 새 기여자들(또는 오랜만에 돌아온 기여자들)이 이것들을 빠르게 익힐 수 있게 해주면 프로젝트 시작 시간을 크게 단축시킬 수 있음.

  • 이런 작은 문서/코드로 된 다이어그램 표준들을 팬이었음:

    • README 주도 개발
    • ARCHITECTURE.md
    • ADRs
    • arc42
    • C4
    • 등등.
    • 이제는 git 저장소의 /docs 폴더 안에 Obsidian 볼트를 넣음.
    • 누군가의 표준을 사용하는 대신, Obsidian에서 내 개인 노트를 관리하는 것처럼 문서를 조직하고 리팩터링함.
    • GitHub(GFM)과 Obsidian에서 모두 작동하는 공통의 Markdown 부분집합을 사용하려고 했지만, 결국 포기하고 Obsidian의 마크다운과 그 전용 기능들을 사용함.
    • Obsidian에는 Mermaid와 LaTeX이 내장되어 있고, PlantUML을 위한 플러그인이 있음.
    • 시각적인 그림/다이어그램을 위해 Canvas, DrawIO, Excalidraw가 내장되어 있음.

  • 당시 논의됨:

    • Architecture.md - Feb 2021 (153개의 댓글)
답변달기