# ARCHITECTURE.md 를 추가합시다

> Clean Markdown view of GeekNews topic #3700. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=3700](https://news.hada.io/topic?id=3700)
- GeekNews Markdown: [https://news.hada.io/topic/3700.md](https://news.hada.io/topic/3700.md)
- Type: news
- Author: [xguru](https://news.hada.io/@xguru)
- Published: 2021-02-08T09:49:03+09:00
- Updated: 2021-02-08T09:49:03+09:00
- Original source: [matklad.github.io](https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html)
- Points: 26
- Comments: 1

## Topic Body

- 오픈소스 참여를 쉽게 하기 위해 프로젝트의 아키텍처를 설명하는 파일을 Repo에 추가하자는 글

- 프로젝트에 가끔 기여하는 사람과 핵심 개발자의 가장 큰 차이점은 프로젝트의 아키텍처에 대한 이해도

- 구조에 익숙하지 않으면 패치를 작성하는 시간도 2배이상 걸리지만, 어디를 고쳐야 하는지 위치를 파악하는데에는 10배 이상 많은 시간이 듬

- 고수준 아키텍처를 설명하는 ARCHITECTURE.md 같은 파일을 작성

ㅤ→ 짧게 작성해서 누구나 읽을수 있게, 잘 변경되지 않는 부분들만 정리

ㅤ→ 코드와 동기화 하려고 하지 말고, 매년 2번정도 다시 보기

내용 작성법

ㅤ- 해결하려고 하는 문제에 대한 조감도(Bird's eye view)로 시작

ㅤ- 조금 더 자세한 코드맵 : "X를 하는 것은 어디에 있나요?"

ㅤ- 대략적인 모듈과 이들의 관계를 설명 : 각 모듈이 하는 일은 다른 문서로 연결

ㅤ- 중요한 파일,모듈,타입 들의 이름을 적을것

ㅤㅤ→ 읽는 사람이 이름으로 검색해볼 수 있게 하고, 직접 링크는 하지말 것(연결이 깨질수 있으니)

ㅤ- 레이어와 시스템간의 경계를 명시

* 좋은 예제

- Rust Analyzer 의 Architecture.md - https://github.com/rust-analyzer/rust-analyzer/blob/d7c99931d05e3723d878bea5dc26766791fa4e69/docs/dev/architecture.md

- Caddy Architecture : https://caddyserver.com/docs/architecture

## Comments



### Comment 4419

- Author: xguru
- Created: 2021-02-08T09:49:13+09:00
- Points: 2

그리고 메인 README.md 에 가능하면 프로젝트의 각 폴더에 대한 설명을 넣어달라는 의견도 좋네요

- https://news.ycombinator.com/item?id=26050082

예제 : https://github.com/diem/diem/tree/master/consensus#how-is-this-module-organized

가능하면 각 폴더에 설명을 넣고, 깃헙이 폴더에 README가 있으면 그 내용을 상위에서 보여주면 좋긴 하겠어요

관련해서 Architecture Decision Records 도 참고하세요

- ADR을 써야 하는 이유 https://news.hada.io/topic?id=2665