writing-stylelisted

# writing-style — 리뷰·PR·리포트 리뷰 코멘트·PR 본문·조사 리포트를 쓰는 문체와 구성 규칙이다. **적용 방법**: 「먼저」·「구성 규칙」·각 문서 유형 절은 **언어 무관** — 어느 언어로 쓰든 적용한다. 문장 단위 규칙은 출력 언어의 절을 따른다 — 한국어면 「문장 규칙」, 영어면 맨 아래 「English prose rules」. 두 절은 번역본이 아니라 **각 언어의 독립 규범**이다. ## 먼저 — 무엇을 쓰는 글인가 **대상에 따라 파일명 규칙이 정반대다.** 이것을 먼저 정하지 않으면 반대로 쓴다. | 글 | 파일명·행번호 | 이유 | |---|---|---| | **리뷰 코멘트** | **반드시 병기** | 읽는 사람이 그 자리를 열어야 한다 | | **조사·분석 리포트** | **반드시 병기** | 주장의 근거이고, 검증할 수 있어야 한다 | | **PR 본문** | **쓰지 않는다** | 변경 목록은 diff 가 이미 보여준다. 여기서 할 일은 **무엇이 달라지는가**다 | | **다른 팀에 답하는 코멘트** | 쓰지 않는다 | 상대는 내 코드를 열지 않는다. 좌표 대신 **어떤 조건에서 그렇게 되는지**를 적는다 | | **커밋 메시지 본문** | 쓰지 않는다 | PR 본문과 같다 — squash 되면 그대로 커밋 본문이 된다 | PR 본문의 기준은 이것이다 — **파일을 하나도 열지 않고 읽어도 무엇이 어떻게 바뀌는지 알 수 있는가.** ## 문장 규칙 ### 완전한 문장으로 쓴다 **압축체·명사 나열·전보문을 쓰지 않는다.** 무엇이 문제고, 왜 문제고, 어떻게 고치는지가 문장으로 드러나야 한다. ``` 나쁨 설정값 해석 실패 시 500 발생. 반경 과다. 좋음 설정값을 지역 id 로 해석하지 못하면 500 이 납니다. 그런데 그 설정값과 아무 관계 없는 다른 지역 사용자의 요청까지 함께 실패하므로, 영향 범위가 실제 원인보다 훨씬 넓습니다. ``` ### 완전한 문장이지 긴 문장이 아니다 위 규칙은 **전보문을 막으려는 것**이지 길게 쓰라는 뜻이 아니다. 둘을 헷갈리면 문장은 완전한데 아무도 안 읽는 글이 된다. ``` 나쁨 왜 경로를 옮기지 않았나 — 그 경로는 두 가지를 함께 따릅니다. 기존 클라이언트가 POST /orders/{id}/refund 를 호출하고 있고(하위 호환 유지가 전제), 부모 리소스 아래 하위 리소스를 두는 것이 이 저장소의 URL 규약입니다. 경로를 밖으로 빼면 호환이 깨져 공지가 필요한 사안이 됩니다. 테스트 한 줄을 지키려고 클라이언트 계약을 바꾸는 셈이고, 저는 이쪽이 더 비싸다고 봅니다. 좋음 경로를 옮기는 대신 테스트가 보는 범위를 /refund 아래로 좁혔습니다. 이 경로는 기존 클라이언트가 쓰는 그대로이고 URL 규약에도 맞아서, 테스트에 맞추려고 경로를 바꾸는 것은 순서가 뒤바뀐다고 봤습니다. ``` **세 가지가 달라졌다.