프로그래밍 일반

[우아한 테크코스 6기 - 프리코스(프론트엔드)] 회고 2: README.md 작성법

tea-tea 2023. 11. 21. 10:04

이 시리즈는 우아한 테스코스 6기의 프리코스 과정에서 유용했던 내용을 주제 별로 정리하고 있습니다.

 

# 목차

  • README.md 란?
  • 기본 구성
    • 컨셉
    • 기능
    • 예외 상황 테스트
  • 추가 구성 
    • 목차(네이게이션)
    • 디자인 구조
  • 작성 형식 팁

# README.md 란?

프로젝트를 설명하는 문서이며 우아한 테크코스(우테코)는 프로젝트의 컨셉과 기능, 예외 상황 테스트 목록을 우선으로 구성하라 조언합니다. 그리고 상황에 따라서 목차, 디자인 구조, 세부 기능 설명을 넣으면 됩니다.

 

* 예시는 아래 링크를 참조했습니다. 이 글 자체에 부분적으로 실어놨으니 예시 전체를 보고 싶은 경우에 참고하세요.

https://github.com/charchar111/javascript-christmas-6-charchar111/tree/main/docs

# 기본 구성 

컨셉

프로젝트의 목적이 무엇인지 어떻게 작동하며 무엇을 하는지, 어떤 특징이 있는지 추상적 수준에서 설명하는 부분입니다. 이 부분에서 주의할 건 프로젝트의 작동방식이나 소스코드(메소드 및 필드)를 세세히 설명하진 않습니다.

 

* 예시 🔽

----------

개요

  • 우아한 테크코스 프리코스 4주차 과제의 제출본이자 학습용이며, 아래는 앱의 컨셉에 대해서 다룹니다.
  • 이 앱은 12월 크리스마스 할인 이벤트를 위해서 제작되었습니다. 앱으로 음식을 예약하면 예약 날짜, 주문 음식, 총 금액에 따라 복수의 할인 혜택을 받고 그 내역을 출력합니다.
  • 디자인은 mvc 패턴을 따랐으며, 유효성 검사는 각 기능 모듈에서 실시합니다.

----------

 

독자를 고려하여 특징을 추가해도 좋습니다. 예컨대, 학습용 프로젝트라면 이 프로젝트에서 어떤 학습 목표를 세웠는지 작성하세요.(ex: 메소드를 15줄 이하로 제한했다.) 실무용 프로젝트라면 프로젝트의 차별화 점에 대해 다뤄주세요. 예컨대, next js는 홈페이지 소개 부분에서 서버 사이드 렌더링, SSG,  css support 등에 대해 서술합니다.

기능

유저가 실제로 앱을 이용한다 가정할 때 필요한 기능을 작성합니다. 이 때, 각 기능은 한 가지 기능만 하도록 세분하여 작성하는 게 좋습니다. 작성 순서는 유저의 실제 이용 과정에 맞춰 나열하는 것이 한 가지 방법입니다.

 

* 예시 🔽

----------

방문 날짜 및 메뉴 설정

  • 방문 날짜를 입력받는다.(사용자 입력)✅
  • 주문할 수 있는 메뉴를 출력한다.✅
  • 주문 메뉴와 개수를 입력받는다.(사용자 입력)✅
  • 주문 메뉴와 개수, 날짜를 객체로 변환해서 할인 로직으로 넘긴다.✅
  • test 파일 : DomainTest.js✅

유저의 입력 정보 출력

  • 주문한 메뉴를 출력한다.✅
  • 할인 전 총 주문 금액을 출력한다.✅
  • test 파일: x

할인 로직

  • 증정 이벤트 적용 여부를 판단하고 출력한다.✅
  • 총주문 금액을 기준으로 할인 로직의 실행 여부를 1차 판단한다.✅
  • 날짜를 기준으로 어떤 할인 로직을 실행할 지 판단한다.✅
  • 크리스마스 디데이 할인 금액을 계산한다.✅
  • 평일 할인 금액을 계산한다.✅
  • 주말 할인 금액을 계산한다.✅
  • 특별 할인 금액을 계산한다.✅

혜택 내역 출력, 이벤트 배지 출력

  • 할인 혜택과 총혜택 금액을 출력하고 이벤트 배지를 부여한다.✅

----------

 

해당 부분에서는 각 기능이 어떤 인풋을 받고 어떤 아웃풋을 산출하는지 서술하진 않았습니다. 하지만, 문서를 누가 읽느냐에 따라서 간략하게 기능의 형식(함수 인자, 산출 형식) 에 대해 적어주는 것도 좋습니다. 예컨대, 개발자를 위한 공식문서라면 함수 형식을 추가해주는 게 좋을 것 같습니다. 반면, 위 문서는 비개발자인 기획 부서가 읽을 거라 가정되었으므로 함수 형식을 추가하지 않았습니다.

예외 상황 테스트

각 기능 별로 발생할 수 있는 예외 상황을 정리합니다. 특히 유저의 입력은 오류 가능성이 있는 데이터 값이 들어올 수 있으므로 유효성 검사에 각별히 신경 써야 합니다.

 

* 예시 🔽

----------

방문 날짜 입력

  • 방문 날짜가 숫자가 아니거나 1 이상 31 이하의 정수가 아니면(ex: 32, 2w) 에러를 일으킨다.✅
  • 위 상황에서 에러가 발생하면 에러메시지를 송출하고 다시 입력을 받는다. 이 과정을 반복한다.✅

메뉴 주문

  • 메뉴 주문은 "$메뉴1-$숫자,$메뉴2-$숫자2"의 형식이어야 한다. 발생 가능한 에러는 다음과 같다.
    • 메뉴가 메뉴판에 없는 경우✅
    • 중복 메뉴를 입력한 경우✅
    • 숫자가 정수가 아니거나 0이거나 음수인 경우✅
    • 숫자를 안 적은 경우✅
  • 주문 시 음료만 주문할 수 없다.✅
  • 메뉴는 한 번에 최대 20개까지만 주문할 수 있다.✅

----------

 

대부분의 예외 상황 테스트는 기능 목록과 매치되는게 좋습니다. 즉, 한 가지 기능을 계획하면 발생 가능한 예외 상황을 함께 작성해주는 겁니다. 이렇게 작성하는 이유는 테스트와 관련있습니다. 다른 글에서 자세히 다루겠지만, 앱이 잘 돌아가는 지 테스트하려면 앱 전체를 테스트 하는 것 뿐만 아니라 각 기능 별로 테스트를 하는 것도 필요합니다. 따라서, 예외 상황에 대한 테스트 코드를 기능 별로 나눠주면 기능 테스트가 좀 더 수월해집니다.

# 추가 구성

목차(네비게이션)

긴 문서를 읽는 독자는 전체를 완독하기 보단 필요한 부분만 읽고 싶어하기도 합니다. 이런 분들을 위해서 문서 최상단에 목차를 마련해주세요. 특히 마크 다운은 쉽게 네비게이션 기능을 구현할 수 있습니다. 여기서 네비게이션이란, 링크를 클릭하면 해당 문단으로 스크롤이 이동하는 기능입니다. 추가로 목차 각 문단마다 최상단의 목차로 돌아갈 수 있도록 링크를 만들어주면 읽기 더 편할 겁니다. (링크의 구현 형식은 아래의 #작성 형식 팁에서 다룹니다)

 

* 예시: 깃허브의 README.md에서 목차와 문단의 네비게이션을 이용할 수 있습니다.

https://github.com/charchar111/javascript-christmas-6-charchar111/tree/main/docs#%EB%AA%A9%EC%B0%A8

디자인 구조

소스 코드는 다양한 모듈로 분할되어 있고 모듈 마다 메소드와 필드, 상수 등으로 분리되어 있습니다. 만약 다른 개발자와 협업이나 리뷰를 한다면, 이런 부분에 대해서 서술하는 것도 좋습니다. 디자인 구조는 프로젝트 초반부터 너무 자세히 작성하지 마세요. 이 때는 추상적 수준에서 앱의 컨셉과 기능, 예외 상황을 계획하는 단계라 구현 과정에서 얼마든지 구조가 바뀔 수 있기 때문입니다.

* 예시 🔽

----------

  • index: 프로젝트의 시작점으로 새로운 App 인스턴스를 생성하고 실행합니다.
  • App: 앱의 최상위 층위로 controller를 작동합니다.

  • controller: 프로젝트의 핵심기능을 추상적인 큰 수준에서 작동합니다.
    • userSetting: 유저의 예약 날짜와 주문을 입력 받음
    • readMenuAndOrder: 주문을 지정된 문자열로 변환함
    • previewBenefit: 날짜와 주문 메뉴를 인자로 할인 로직을 적용하고 출력함

  • views: ui기능으로 정보를 입출력합니다.
  • calcultate: 할인 로직의 적용 여부를 판단하고 실행합니다.
    • makeOrder, makeNewOrder : 주문 인자를 객체로 변환합니다.
    • total: 주문의 총금액을 반환합니다.
    • triggerSwitchEvent: 할인 로직이 적용되기 위한 선결 조건을 검사합니다.(최소 주문금액, 메뉴)
    • switchEvent: triggerSwitchEvent을 통과했다면 어떤 할인 로직이 적용될지 검사합니다.
    • triggerDiscount, makeCheckBit :switchEvent의 하위 로직입니다. 비트 연산자로 각 할인 로직의 실행 여부를 판단합니다. - 할인 로직: DiscountDDay, DiscountWeekday, DiscountWeekend - 유틸 로직 : findDiscountMenu(각 메뉴가 할인 대사인지 검사합니다.) 

 

  • contstant : 메뉴, 메뉴의 카테고리, 할인 로직의 주요 상수
  • validate는 별도의 모듈이 없습니다. 대신, 각 모듈 마다 validate 메소드가 있습니다. 

----------

여기서 다루진 않았으나, 프로젝트의 규모에 따라서 기능 레퍼런스를 추가하는 것도 고려할만 합니다. 

# 작성 형식 팁 

제목 크기 - h1, h2, h3

문서를 대주제와 중주제, 소주제로 나눠서 작성하면 각 주제마다 내용을 찾아보기 편해집니다.
마크다운 문법에서는 문장 왼쪽에 #을 붙이고 한 칸 띄우면, 글씨 크기가 커지고 볼드 처리가 됩니다. (html에서 <h1> 태그를 생각하면 됩니다.) #의 갯수는 한번에 1~6까지 가능하고 1~2는 자동으로 문장 하단에 구분선이 붙습니다.

## 기능
<!-- <h2>개요</h2> -->
<!-- border-bottom이 자동으로 생김 -->

### 방문 날짜 및 메뉴 설정
<!-- <h3>개요</h3> -->
<!-- h3부터는 border-bottom 생성이 안됨  -->

 

네비게이션

목차에서 특정 주제를 클릭하면 스크롤이 해당 부분으로 이동하는 걸 본 적 있나요?

반대로 특정 주제를 읽고 나면 최상단의 목차로 다시 이동하고 싶지 않나요?

이럴 때 네비게이션을 쓰면 클릭 하나만으로 전부 가능합니다.

<!-- 형식 
[링크의 내용](# 이동할 타이틀)
<a href="#url인코딩된 타이틀명">링크의 내용</a> -->

<!-- 예시 -->
## 개요

- 우아한 테크코스 프리코스 4주차 과제의 제출본이며, 아래는 앱의 컨셉에 대해서 다룹니다.
- 12월에 크리스마스 이벤트를 진행합니다. 이 앱으로 음식을 예약하면 예약 날짜, 주문 음식, 총 금액에 따라 복수의 할인 혜택을 받습니다.
- [기능](#목차)
	<!-- 클릭하면 목차 타이틀로 스크롤이 이동합니다 -->
	<!-- <a href="#%EB%AA%A9%EC%B0%A8">하술된 각 기능을 구현합니다</a> -->
    
- 디자인은 mvc 패턴을 따랐으며, 유효성 검사는 각 기능 모듈에서 실시합니다.
  - [디자인](#디자인)
  	<!-- 클릭하면 디자인 타이틀로 스크롤이 이동합니다 -->
	<!-- <a href="#%EB%94%94%EC%9E%90%EC%9D%B8">디자인</a> -->

## 목차
	<!-- 중략 -->
    
    
## 디자인

 

 

리스트 나열

무언가를 간략히 개요만 나열할 때는(목차처럼) 리스트를 한번 써보세요. 훨씬 보기 좋을 겁니다.

## 디자인

- App: 프로젝트의 시작점으로 controller를 작동합니다.
  <br/>

- controller: 프로젝트의 핵심기능을 추상적인 큰 수준에서 작동합니다.

  - userSetting: 유저의 예약 날짜와 주문을 입력 받음
  - readMenuAndOrder: 주문을 지정된 문자열로 변환함
  - previewBenefit: 날짜와 주문 메뉴를 인자로 할인 로직을 적용하고 출력함
    <br/>

- views: ui기능으로 정보를 입출력합니다.

 

🔽🔽

디자인

  • App: 프로젝트의 시작점으로 controller를 작동합니다.
  • controller: 프로젝트의 핵심기능을 추상적인 큰 수준에서 작동합니다.
    • userSetting: 유저의 예약 날짜와 주문을 입력 받음
    • readMenuAndOrder: 주문을 지정된 문자열로 변환함
    • previewBenefit: 날짜와 주문 메뉴를 인자로 할인 로직을 적용하고 출력함
  • views: ui기능으로 정보를 입출력합니다.

체크 리스트

README는 작성자 본인을 위한 문서이기도 합니다. 프로젝트에서 작성 중인 문서는 어떤 기능을 구현했는지에 대한 체크리스트로 사용할 수도 있습니다. 이런 식으로요

  • 방문 날짜를 입력받는다.(사용자 입력)✅
  • 주문할 수 있는 메뉴를 출력한다.✅