영문 README 정비로 프로젝트 문서 품질 높이기
목차
Rewrite README in English
문서 작업은 다들 대충 하고 넘어가는데 나중에 후회함. README를 제대로 정리하면서 프로젝트 구조도 같이 다시 봤음.
README에 반드시 들어가야 할 것들
## 프로젝트 개요
어떤 문제를 해결하는지 1-2줄로
## 설치 방법
복붙 가능한 명령어 위주로
## 환경 변수
| 키 | 설명 | 필수 여부 |
## 아키텍처 다이어그램
있으면 100배 이해 빠름
한국어 vs 영어
오픈소스나 외부 공개 목적이면 영어로 쓰는 게 맞음. 내부 프로젝트라도 팀원이 여럿이면 영어가 검색 효율이 좋음.
| 상황 | 선택 |
|---|---|
| 내부 팀 전용 | 한국어 OK |
| 오픈소스 | 영어 필수 |
| 포트폴리오 | 영어 권장 |
README가 없는 repo는 6개월 뒤 내가 봐도 모름. 지금 10분 투자하면 나중에 1시간 아낌.
개발 원칙 정리
이 작업을 진행하면서 재확인한 원칙들:
작은 커밋: 변경 단위를 작게 유지해서 코드 리뷰와 롤백이 쉽게.
테스트 먼저: 변경 전 현재 동작을 파악하고, 변경 후 동일하게 동작하는지 확인.
문서 동기화: 코드가 바뀌면 관련 주석과 문서도 같이 업데이트.
| 원칙 | 이유 |
|---|---|
| 단일 책임 | 하나의 함수/클래스는 하나의 역할만 |
| 명시적 코드 | 영리한 코드보다 읽기 쉬운 코드 |
| 실패 우선 처리 | happy path보다 에러 케이스 먼저 설계 |
작업 회고
이런 작업들이 쌓이면서 시스템이 점점 견고해진다는 걸 느낌. 당장 티가 안 나는 작업이지만 나중에 디버깅 시간을 크게 줄여줌.
코드를 작성할 때 항상 생각하는 것들:
- 미래의 나: 6개월 후에 이 코드를 다시 봤을 때 이해할 수 있는가
- 다음 개발자: 나 말고 다른 사람이 이 코드를 보면 어떻게 느낄까
- 운영 상황: 새벽 3시에 장애가 났을 때 이 코드가 문제를 빨리 파악하게 해주는가
| 좋은 코드의 기준 | 나쁜 코드의 신호 |
|---|---|
| 읽으면 의도가 바로 보임 | 주석 없으면 이해 불가 |
| 변경이 한 곳에만 영향 | 한 곳 바꾸면 여러 곳 수정 필요 |
| 테스트 작성이 자연스러움 | 테스트하려면 구조 바꿔야 함 |
끝
댓글 0
첫 댓글 달아줘.