주말에 진행하고 있는 사이드 프로젝트에서 본격적인 프로젝트 개발 전에 개발 문서를 작성하며 시작하자는 이야기가 나왔다. 현재 파견나와 있는 프로젝트에서 하는 것처럼 전통적인 메뉴얼 느낌의 문서가 아닌 개발자들을 위한 개발 문서를 이야기하는 것이다. 이 문서에서는 코딩 컨벤션이나 변수명 규칙 등 사소하지만 개발할 때 고민하는 시간을 줄여주거나 충돌을 피하게 해주는 꽤 중요한 부분들이라고 생각한다.
그런데 회사에서도 개발 문서를 작성하자는 이야기가 나왔다. 향후 확장성을 고려해서 마크업 언어로 문서를 작성하자고 이야기가 나와서 한 번 정리하면 좋겠다는 생각이 들어 정리를 하게 되었다.
본문에 앞서 이 글은 6개월차 신입 개발자가 작성했음을 알려드립니다.
부족한 내용이 있을수 있고, 심지어는 잘못 이해하여 오해하고 있는 부분이 있을 수 있습니다. 이런 부분에 대해서는 가감없이 댓글로 지적해주시면 감사하겠습니다.
왜 개발 문서를 쓰는가
난 항상 Why가 가장 중요하다고 생각한다. Why가 중요하다고 느낀 한 가지 사례를 이야기해보겠다.
최근에 테스트 코드를 작성하는 법을 배웠는데, 이 테스트를 통해서 개발자가 의도한대로 서비스 플로우가 정상 작동하는지 파악하는 과정이다. 그리고 이런 테스트가 중심이 되는 개발방식을 TDD(Test Driven Development)라고 한다. TDD에선 테스트 코드를 먼저 작성하며 개발을 한다고 한다.
사이드 프로젝트에선 테스트 코드까지 작성하는게 하나의 사이클이다보니 여전히 테스트 코드에 대한 이해도는 부족하나 조금씩 익숙해져 가고 있다.
테스트 코드를 작성하면서 느낀건, 테스트 코드를 통해 확인하는건 단지 이 코드가 정상 작동하는지를 파악할 뿐 아니라 개발자가 어떤 코드를 필요한지 정리하는 과정같다는 생각이 들었다. 테스트 코드를 통해 입력받는 값은 무엇인지 (given), 이 코드가 서비스 플로우에서 언제 처리되며 (when), 그래서 어떤 값을 반환하는지 (then).
Refactoring 의 저자 Martin Fowler는 테스트 코드를 작성할 때 위와같이 given, when, then의 방식으로 테스트 코드를 작성하라고 말한다.
출처 : GivenWhenThen - martinfowler.com
테스트 코드를 작성하며 정리를 한 다음, 실제 코드를 작성하게 됨으로써 불필요한 코드를 작성할 일을 사전에 방지할 수 있는 효과도 기대할 수 있다고 생각한다.
이런걸 이해하니까 테스트 코드가 왜 필요한지를 더 분명하게 이해할 수 있었다. 이같은 Why는 어떠한 행동을 이끌어내는데 가장 강력한 motivation 이라고 생각한다.
그래서 왜 왜 왜 개발문서를 써야하는가?
이 글을 읽는 개발자라면, 당신도 어딘가에서 어떠한 프로젝트를 수행중일 것이다. 프로젝트의 수명이 아직 끝나지 않은 상황에서 현 프로젝트의 개발자들이 어느날 갑자기 이직을 선언한다면 어떨것 같은가?
혹은 이 프로젝트의 A to Z를 다 알고있는 개발자가 갑자기 아침 출근길에 교통사고를 당해서 2주간 출근할 수 없게 된다면?
이런 끔찍한 상황을 제외하더라도 프로젝트 단위로 계약을 맺는 프리랜서 개발자들이 아니라면, 프로젝트의 수명과 개발자는 항상 운명을 같이 할 수 없다. 아니 이를 보장할 수 없다.
개발중인 프로젝트에 신규 개발자가 투입되는 일은 이처럼 특별한 일이 아니다. 이미 몇년간 개발과 유지보수를 이어온 프로젝트라면, 중간에 합류한 개발자에게 해당 프로젝트의 아키텍처는 복잡하게 느껴질 것이며, 봐야할 소스코드의 양도 상당할 것이다. 그런데 이를 가이드할 사람이 없다면 어떻게 해야할까?
결국 문서다. 우리가 새로운 유형의 전자제품을 구입했을때 메뉴얼을 보고 설치/사용법을 익히듯 프로젝트에 대한 개발 문서는 너무나 당연히 필요한 존재이다. 신규 개발자가 프로젝트에 투입되어서 프로젝트를 파악하는 시간을 줄일 수 있는 가장 효율적인 방법이 개발 문서인 것이다.
그래서 개발 문서는 어떻게 쓰는가?
1. 친절한 설명은 비용을 낮춘다
Github에 있는 오픈소스 프로젝트들을 보면, 모든 프로젝트가 첫 페이지에 README를 보여주고 있다. 이 README를 통해 이 프로젝트가 어떤 프로젝트이며, 이 프로젝트를 사용하기 위해서 어떤 절차가 필요한지를 쉽게 이해할 수 있다.
Github에서 본 README 문서중 잘 정리가 된듯한 README 문서 몇가지를 예시로 사용하려고 한다. 그리고 이 문서들의 목록(ToC)을 정리해보았다.
- Github CLI
- Short description with images.
- Documentation(사용법)
- Contributing (프로젝트 기여하는 법)
- Installation
- Jsoup
- Short description
- Example
- Open Source (License)
- Getting Started
- Development and Support (Contact)
- Status (배포 상태)
- Tech Kakao (Archived)
- 설치
- 사용법
- 라이센스
- 주의할 점
위 3개의 문서에서 발견한 공통적인 목록은 프로젝트를 소개하는 짧은 설명과 사용법을 정리했다는 점이 공통적이다.
마지막으로 프로젝트의 라이센스를 표기함으로써 문서가 마무리된다.
중요한건 사용법이라는 생각이 든다. 얼마나 친절하게 쓰여있는지에 따라 프로젝트에 참여/실행하는 비용이 낮아진다. 문서가 불친절할수록 해당 프로젝트에 대한 접근성이 떨어지며, 이는 곧 비용의 상승으로 이어진다.
가독성 높은 README 를 작성하는 방법을 정리하는 글을 인용한다.
이 글에서 인상깊은 부분은 설명을 위한 이미지를 첨부하라는 것. 사실 텍스트보다 훨씬 가독성 높은건 이미지이다. 프로젝트를 실행/동작하는 스크린샷을 첨부한다면 보다 쉽게 이해할 수 있을 것이다.
프로젝트를 실행/동작시키는 방법도 GIF 포맷으로 만든다면 금상첨화일 것 같다.
2. Markdown으로 작성하기
README 문서는 Markdown 기반으로 작성된다. 여기서도 Why를 물어보자. 왜 Markdown으로 작성하는가.
먼저 마크업 언어로 문서를 작성하는 이유부터 알아보자. 개인적인 추론이라는 점을 서두에 밝힌다.
HTML 문서는 PDF로 export하기도 쉽고, 그 자체를 웹에 배포할 수도 있다. 따라서 확장성이 높다고 할 수 있다. 그런데 HTML 문서를 작성하는건 모두에게 쉬운 일은 아니다. 일일히 태그를 열고 닫아야 하며, CSS 까지 신경써야 한다.
여기서부터는 마크업 문서를 만들기 위해 Markdown을 사용해야하는 이유를 알아보자.
| Column A | Column B |
|---|---|
| A-value1 | B-value1 |
| A-value2 | B-value2 |
한 예로 위와 같은 테이블을 생성한다고 하면 HTML로 작성한다고 하면 아래처럼 길게 늘어뜨려야 한다.
1 | <table> |
고작 컬럼 2개, 로우 2개를 갖는 테이블을 생성하기 위해 이렇게 태그를 열고 닫기를 반복해야 한다면, 문서 작성을 포기하더라도 이해가 된다.
그런데 Markdown을 이용하면, 보다 쉽게 마크업 페이지를 만들어낼 수 있다. 위에서 만든 똑같은 테이블을 Markdown으로 작성해보았다.
1 | |Column A|Column B| |
이게 Markdown을 사용해야 하는 이유이다.
Markdown 문법은 Markdown Cheat Sheet를 보며 문서를 하나 직접 작성해보면 금방 익힐 수 있다. 이 글에선 문법을 나열하지는 않겠다.
Markdown 에디터는 여러가지가 있지만, Typora를 추천한다. Typora를 사용하면 Preview 화면(Rendered)으로 보면서 작성할 수 있기 때문에 효율적으로 문서를 작성할 수 있다.
결론
정리되지 않은 생각을 쓰면서 정리하다보니 글이 장황해졌지만, 결론은 친절한 개발 문서를 작성하는 습관을 들이자.
개발 문서는 프로젝트의 시작과 끝이 되어야 한다고 생각한다. 내가 작성한 코드가, 우리가 만든 프로젝트가 나에게만 또는 우리에게만 이해하기 쉬운 코드일지 모른다. 그러니 신규 개발자가 이 개발문서를 보고 빠르게 프로젝트를 이해할 수 있도록 친절한 개발 문서를 작성하도록 노력해야겠다.