간결한 영어 (Simple English)
핵심을 평범한 단어로 최대한 적게 말하고 멈추세요. 독자는 세부 사항을 위해 코드를 봅니다.
간결하게
- 요점으로 시작하세요: 무엇을 하는지, 그리고 그 이유가 명확하지 않을 때는 왜 그런지.
- 코드나 diff가 이미 보여주는 내용은 생략하세요: 수정한 파일, 단계 순서, 코드가 처리하는 예외 상황.
- 업계의 간결한 표현을 사용하세요: "사용하지 않는 아이콘 제거", "아무것도 사용하지 않는 아이콘 제거"가 아닌.
- 한 번 말한 사실은 반복하지 마세요.
- 단어를 줄이되, 사실은 줄이지 마세요. 독자가 문제를 이해하는 데 필요한 각 단계를 유지하고, 결과를 명시하세요: "해당 날짜는 CI가 릴리스를 만드는 날과 다를 수 있습니다", "헤딩은 릴리스 날짜 전에 작성됩니다"가 아닌.
명확하게 유지
간결함이 난해함을 의미하지는 않습니다.
- 한 문장에 한 가지 아이디어를 주어와 동사와 함께 쓰세요. 세미콜론, 수수께끼, 슬로건(예: "릴리스 없음, 타입 없음")은 사용하지 마세요.
- 주어를 먼저 놓고 행위자를 밝히세요: "C++가 X를 계산합니다", "X가 C++에서 계산됩니다"가 아닌.
- 단순 시제를 사용하고, 여전히 참인 사실에는 현재 시제를 사용하세요: "QML은 바인딩을 절대 재평가하지 않습니다", "재평가되지 않음"이 아닌.
- 조건은
X이면, Y.형식으로 쓰세요. - 명사가 절 뒤에 있거나 두 개 이상의 명사가 들어갈 수 있는 경우 "그것", "그들", "저것" 대신 명사를 반복하세요.
- "which"와 "whose" 절은 짧게 유지하세요. 절에 긴 주어가 있다면 별도의 문장으로 분리하세요: "Debian과 Ubuntu Qt 패키지에는 그것이 없습니다", ", Debian과 Ubuntu의 Qt 패키지가 생략하는"이 아닌.
- 부정문은 명확하게 표현하세요: "범위를 벗어난 값은 무시하세요", "범위를 지난 값을 취하지 마세요"가 아닌. 목적어를 통해 부정하지 마세요: "수정이 updated()를 내보내지 않았습니다", "수정이 updated()를 내보내지 않음"이 아닌. "nor"는 "neither" 뒤에만 쓰세요.
자연스럽게
텍스트는 영어를 모국어로 사용하는 개발자가 쓴 것처럼 읽혀야 합니다. 구절이 번역처럼 느껴지면, 다시 작성하세요. 다시 작성한 것이 한 단어 더 길어지더라도 말입니다.
- "of" 체인 대신 복합 명사를 사용하세요: "앱 설정", "CSV 파일 대화상자", "Debian 및 Ubuntu Qt 패키지". 복합 명사로 해결되지 않을 때만 소유격을 사용하고(예: "시트의 밀도"), 절대 연속으로 두 번 사용하지 마세요. 구문당 최대 하나의 "of"를 허용합니다.
- 업계에서 흔히 쓰는 동사를 사용하세요: "표시", "보고", "수정", "지원", "처리", "확인". 코드를 사람처럼 만들어 "알려주다", "대답하다", "수행하다"라고 하지 마세요. "own"은 C++ 의미의 소유권에만 사용하세요.
- 개념당 한 단어를 사용하세요: "check" 또는 "verify" 중 하나를 선택하고, "settings" 또는 "options" 중 하나를 선택하여 일관되게 사용하세요.
- 목록에서 관사를 반복하지 마세요: "프레임 및 삭제 버튼".
- 요구사항에는 "must"를, 가능성에는 "can"을 쓰세요. "should", "may", "might"는 피하세요.
- "for example"을 쓰고 "e.g."는 피하세요. 미국식 철자를 사용하세요.
- 다음 단어는 삭제하세요: "leverage"와 "utilize"("use" 사용), "in order to"("to" 사용), "prior to"("before" 사용), "ensure", "simply", "just", "easily", "seamlessly", "robust", "powerful", "comprehensive", "functionality", "it is worth noting that", "with this change", "is designed to", "allows you to" (대신 사물과 그 동사를 명명), "under the hood", "out of the box".
실제 커밋 제목의 전과 후:
| 전 | 후 |
|---|---|
| 앱 설정을 문서 밖에 유지 | 문서에 앱 설정을 저장하지 않음 |
| Graph: 내보내기 실패 시 독자에게 알림 | Graph: 내보내기 오류 보고 |
| CardButton 추가, 객체 상단 행의 아이콘 버튼 | CardButton 추가, 객체 상단 행의 아이콘 버튼 |
| Sampler: 이산 객체의 범위를 넘는 값 취하지 않음 | Sampler: 이산 객체 값이 범위를 벗어나면 무시 |
| 다른 날짜의 노트가 포함된 전체 릴리스 중지 | 전체 릴리스 전에 릴리스 노트의 날짜 확인 |
| Ubuntu 26.04, 해당 Qt 패키지로 빌드 | Ubuntu 26.04, 해당 Qt 패키지로 빌드 |
텍스트 종류별
커밋 메시지
- diff 없이도 의미가 통하는 짧은 명령형으로 제목을 작성하세요: "문서 값을 설정 패널 범위로 제한", "패널 범위 내에서 문서의 숫자 유지"가 아닌.
- 하나의 커밋은 한 가지 작업을 합니다. 본문에 두 번째 주제가 필요하면 커밋을 분할하세요.
- 본문은 코드가 지금 하는 일로 시작하고, 짧은 이유를 덧붙이세요.
- 제목을 넘는 사실은 "또한"으로 표시하세요: "두 읽기 모두 알 수 없는 키를 건너뜁니다. 새 버전에서 일부를 추가할 수 있기 때문입니다."
- 독자가 이미 아는 배경은 생략하세요. diff를 다시 설명하거나 변경을 변명하지 마세요.
코드 주석
- 기본적으로 주석을 작성하지 마세요. 코드가 보여주지 않는 이유, 숨겨진 불변 조건, 또는 해결책이 있을 때만 작성하세요.
- 코드가 하는 일, 그 결과, 그리고 이유를 각각 짧은 문장으로 말하세요. 코드가 이미 보여주는 부분은 생략하세요.
- API 이름을 명시하고 은유를 사용하지 마세요. 명령형도 괜찮습니다: "동일한 쓰기 건너뛰기: 여전히 mtime 업데이트".
- 동료가 "왜 여기 있지?"라고 물을 때 줄 수 있는 주석을 작성하세요. 구체적인 효과를 명명하세요(예: "xmin이 왼쪽에 유지됨"), 요약(예: "경계가 제자리에 있음")이 아닌.
예시:
- 전:
// 세로 목록은 너비를 비밀로 유지하므로 스타일이 잘못된 핸들을 그립니다 - 후:
// 세로 ListView는 contentWidth를 -1로 남겨두며, 스타일이 축소된 핸들로 렌더링합니다 - 전:
# 러너의 glib과 libsystemd는 새로운 glibc가 필요하므로 AppImage는 호스트의 glib과 libdbus를 사용합니다. linuxdeploy는 여전히 그들만 필요한 라이브러리를 복사하므로 목록에도 그 이름이 포함됩니다 - 후:
# glib, libdbus 및 해당 종속성을 번들하지 마세요. 그러면 AppImage가 호스트 버전을 로드합니다. Ubuntu 26.04 버전은 glibc 2.43이 필요하며, 이는 오래된 배포판에는 없습니다.
문서
- 코드가 오늘 하는 일을 설명하세요. 대상을 명명하고 용도를 설명한 후, 세부 사항이 있는 파일을 가리키세요.
- 세 개 이상의 병렬 항목은 글머리 기호 목록으로 작성하세요.
- 스타일, 모듈, 식별자 이름은 백틱으로 감싸세요:
FluentWinUI3. - 변경될 수 있는 타사 소프트웨어에 대한 사실은 "현재" 또는 버전을 명시하세요: "Debian 및 Ubuntu Qt 패키지에는 현재 없습니다."
오류 메시지: 무엇이 발생했는지, 알려진 원인, 그리고 어떻게 해야 하는지. 사과하지 마세요.
도구 설명: 위젯이 설정하는 내용.
에이전트용 지침: 문장당 하나의 규칙, 조건을 먼저.
그대로 둘 것
코드, 식별자, 명령어, 경로, 인용된 메시지, 제품명, 버튼, 탭, 필드, 메뉴 항목의 이름.
전달하기 전에
텍스트를 독자로서 한 번 읽으세요. 그 독자에게 도움이 되지 않는 각 문장을 삭제하세요. 남은 모든 문장이 처음 읽을 때 이해되고 평범한 영어처럼 들리는지 확인하세요.
채팅에서 같은 내용을 설명했다면 둘을 비교하세요. 채팅 버전이 더 명확하다면 그것을 사용하세요.