오픈소스 프로젝트를 관리하고 코드 라인이 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가 내장되어 있음.
Hacker News 의견