[모각코 1031] 안드로이드 프로젝트 README.md 작성하기

 소프트웨어학부 학부생이 된지도 어언 2년이 지났지만 제대로 부끄럽게도 나는 한 번도 README 파일을 제대로 작성한 적이 없었다.

솔직히 프로젝트가 아니면 굳이 리드미 파일을 작성해야 하나? 하는 생각도 있었고 프로젝트형 과제를 받은 적도 몇 없었다.

하지만 저번 1학기 컴퓨터 네트워크로 TCP IP 통신 구현 프로젝트에서 README를 하나도 작성하지 못해 이번에는 열심히 써보려고 한다.

1학년 당시 스스로 잘 작성했다고 생각했던 무언가

https://github.com/Choi-Jiwon-38/ET_CAT

GitHub - Choi-Jiwon-38/ET_CAT: 2021-2 국민대학교 소프트웨어 프로젝트 II - AD 프로젝트

사진이 작아서 안보인다면 직접 내 깃허브를 방문해서 확인해보록 하자. 맞팔로우도 하도록 하자

 

 

README(리드미)를 작성하는 방법을 알아보기 전!

먼저 우리는 리드미가 무엇이고 왜 써야하는 지 알면 그 구성을 더 빨리 이해할 수 있고 내 프로젝트에 걸맞는 리드미를 작성할 수 있다.

 

README?
 README는 프로젝트에 대한 간단한 설명을 담고 있는 문서
 일반적으로 우리가 GitHub 레포지토리에 들어가면 디렉토리와 함께 보여지는 페이지(문서)
 `markdown` 문법으로 작성되어 확장자는 .md

즉, 리드미 작성은 우리가 열심히 코드를 작성하여 구현한 결과물을 문서화하는 작업이다.

그렇다면 리드미 작성은 왜 해야할까? 우리는 어디에 초점을 맞추어 작성을 해야할까?

 

리드미를 읽는 대상은 경우에 따라 크게 셋으로 나눌 수 있다.

1. 코드 작성자(나) - 아무리 나의 코드여도 오랜 시간이 지난 뒤에 다시 보게 된다면? 꽤나 많은 시간을 들여 코드를 보아야 할 것이다. 소프트웨어의 구조는 어떤지... 이 변수가 어떤 곳에서 작동하는지... 하지만 리드미 파일을 작성한다면 이 부분에서 소요되는 시간을 크게 줄일 수 있다.
2. 프로젝트 팀원(협업자) - 프로젝트의 뼈대 및 핵심 정수들을 리드미에 담기 때문에 작업을  하는 팀원이 원활하게 본인의 일을 진행할 수 있다.
3. 다른 사용자들 - 우리의 레포지토리를 직접 사용하거나 fork하여 가져간 뒤, 재사용하는 경우 사용자들이 사용법을 빨리 캐치할 수 있다.

 

그렇다면 안드로이드 프로젝트 리드미에서는 어떤 부분이 들어가면 좋을까?

아래 내용은 README 작성 예시이며 간단하게 정리하였으니 가볍게 짚고 넘어가면 좋을 듯 하다.

 

1. 설명

프로젝트에 대한 간단한 설명을 담는다.
무엇을 위한 프로젝트인지에 대한 설명을 담으면 된다.
주로 길고 장황한 것 보다는 간단명료하게 작성하는 것이 권장된다.
실행 방법에 대한 설명도 이곳에 들어간다.

2. 개발 환경

프로젝트의 실행 환경에 대한 설명을 담는다.
사용 운영체제나 컴파일러 등에 대하여 작성하면 된다.

 

3. SDK 버전

안드로이드에서 SDK 버전은 애플리케이션의 호환성과 직결되고
애플리케이션의 보안성, 기능성과도 큰 연관이 있기 때문에
리드미에 최소 버전과 타겟 버전 두 가지 모두 적어두면 참고하기 좋다.

4. APIs

사용된 API에 대한 설명을 담는다.
말 그대로 프로젝트에서 사용한 API를 죽 나열해주면 된다.

5. DB import하는 방법

데이터베이스를 사용하는 경우에는
사용자가 원활하게 프로젝트를 실행할 수 있도록
데이터베이스의 사용법을 기재해주면 된다.

6. Screen Shots

애플리케이션 실제 실행 모습을 담는 곳
애플리케이션의 기능이나 목적 등 핵심적인 내용을 시각적으로 보여줄 수 있다.
별다른 양식은 없으므로 자유롭게 작성하면 된다.

7. License

프로젝트가 어떤 라이센스 밑에 있는 지 작성해주면 된다.
라이센스는 다른 사용자들이 우리의 프로젝트를 참조할 때, 준수 사항들을 확인하기 쉽게 도와준다.

 

 안드로이드 프로젝트는 크게 위 키워드들로 나누어 문서화할 수 있다.

이번에 진행한 모바일 프로그래밍 과제의 경우는 위 양식을 조금 수정하여 README 파일을 작성하였다.

 

강해진 리드미 파일

와 벌써 엄청 많이 성장했는걸?

 

자세한 내용은 아래 주소를 참고하면 좋을 것 같다.

데이터베이스 및 API, 라이센스 등은 이번 프로젝트에서 사용하지 않아 제외하고 다른 내용을 중심으로 기술해보았다.

 

https://github.com/Choi-Jiwon-38/2022-MOP

GitHub - Choi-Jiwon-38/2022-MOP: 2022-2 모바일 프로그래밍 수업 (Kotlin)

맞팔해주세요 그럼 이만~

 

다음에는 마크다운 작성법...을 포스팅 하게 될지도??