개발자의 영어,
말보다 글 한 줄이 먼저 읽힙니다
“Why did you do this?”의 결과
이해가 안 가는 줄에 “Why did you do this?”라고 코멘트를 달았습니다. 정말 궁금해서였는데, 다음 날 올라온 답글은 “Sure, I’ll change it.”이 전부였습니다. 이유를 물은 말이 상대에게는 고치라는 말로 읽혔던 것입니다.
해외 팀과 일하면 영어를 말하는 시간보다 쓰고 읽는 시간이 길어지는 경우가 많습니다. 코드 리뷰 코멘트, PR(pull request, 코드 변경을 합치기 전에 올리는 검토 요청) 설명, 이슈 티켓, 슬랙 메시지, 장애 공유가 모두 글이고, 각자 다른 시간에 읽고 답하는 이런 방식을 비동기 소통이라고 부릅니다.
글에는 표정도 목소리도 없어서, 짧게 쓴 문장이 의도보다 차갑게 읽히곤 합니다. 이 글은 개발자가 글로 쓰는 장면을 골라 문장과 어조를 정리했습니다. 회의에서 하는 말과 질문 표현은 다른 글에서 다룹니다.
SUMMARY
개발자의 영어는 글로 쓰는 장면이 많고, 글에서는 얼마나 꼭 해야 하는 일인지와 그 이유를 문장에 직접 적어야 어조가 전해집니다.
- 한 줄로 알리기
- 수위 밝히기
- 틀에 채우기
- 막힘 공유하기
01스탠드업
스탠드업은 어제·오늘·막힘, 세 칸에 한 문장씩이면 됩니다
스탠드업(팀이 매일 짧게 진행 상황을 나누는 시간)에서는 Yesterday, Today, Blockers 세 칸을 한 문장씩 채우는 틀을 흔히 씁니다. 과정은 빼고 결과만 말합니다.
말로 하든 슬랙에 쓰든 틀은 같습니다. 형식은 팀마다 달라서 이 세 칸이 필수는 아니지만, 처음 입을 떼기에는 가장 가벼운 틀입니다. 어제 한 일을 다 말하면 길어지고, 무엇이 끝났는지만 말하면 짧아집니다.
Yesterday I finished the retry logic for uploads,어제 끝낸 일today I'm picking up the pagination ticket,오늘 할 일and I'm blocked on staging access.막힌 것(없으면 생략해도 됨)
staging은 출시 전에 시험해 보는 환경입니다. 막힌 것이 없을 때는 빼도 되고, 분명히 하고 싶으면 No blockers.라고 짧게 덧붙입니다.
- Yesterday: finished upload retries. Today: pagination ticket. Blockers: staging access.어제: 업로드 재시도 완료. 오늘: 페이지네이션 티켓. 막힘: 스테이징 접근.슬랙 스탠드업은 조각으로 써도 된다. Done / Next / Blocked로 쓰는 팀도 있다
- I wrapped up the retry logic for uploads.업로드 재시도 로직을 마무리했습니다.wrap up = 끝맺다. finished보다 구어체
02코멘트 수위
리뷰 코멘트는 얼마나 꼭 고쳐야 하는지부터 밝힙니다
글로 달린 코멘트는 어조가 안 보이므로 nit, suggestion, blocking처럼 수위를 문장 맨 앞에 적습니다. 받는 사람이 무엇부터 고칠지 바로 정할 수 있습니다.
PR에 올라온 변경을 읽고 줄마다 코멘트를 다는 것이 코드 리뷰입니다. 코멘트가 모두 같은 무게로 보이면 어디서부터 고칠지 알 수 없어서, 많은 팀이 수위를 알리는 접두어를 붙입니다. 약속은 팀마다 다릅니다.
- 사소한 것(nit)nit: could we rename this to retryCount?사소한 건데, 이름을 retryCount로 바꿀까요? (nit은 nitpick, 트집)
- 제안Suggestion: we could pull this into a helper. Fine to leave it if you'd rather keep it here.제안: 헬퍼 함수로 뺄 수도 있어요. 여기 두고 싶으면 그대로 괜찮아요.
- 고쳐 달라는 요청Could we add a test for the empty list?빈 목록에 대한 테스트를 하나 추가할 수 있을까요?
- 병합을 막는 지적Blocking: this writes the access token to the logs. Can we remove that before we merge?병합 전 필수: 이 코드가 액세스 토큰을 로그에 남겨요. 병합 전에 뺄 수 있을까요?
접두어 없는 Could we…?는 고쳐 주면 좋겠다는 요청으로 읽히는 편입니다. Could you…?보다 we가 같이 책임지는 코드라는 느낌을 주어서 지시처럼 들리지 않는 경우가 많습니다.
KEY LINE
Is this blocking, or just a preference?03코멘트 어조
코멘트가 차갑게 읽히는 건 짧아서보다 주어와 근거가 없어서인 경우가 많습니다
짧은 코멘트 자체는 문제가 없습니다. 사람을 주어로 지적하거나 이유 없이 결론만 던질 때 차갑게 읽힙니다.
가까운 팀원에게 “Typo.”나 “Remove this log.”만 남기는 것은 흔하고, 읽는 쪽도 빠릅니다. 조심할 곳은 설계를 건드리는 코멘트와 처음 일하는 사람에게 다는 코멘트입니다.
차갑게 읽힘
Why did you do this?부드럽게I might be missing context, but why do we need the second call here?
글에서 Why did you…?는 추궁처럼 읽힐 수 있습니다. 놓친 것이 있을 수 있다는 말을 앞에 둡니다.
차갑게 읽힘
You forgot to handle null.부드럽게This doesn't handle null yet. Could we add a check?
사람이 주어이면 지적이 되고, 코드가 주어이면 사실이 됩니다.
차갑게 읽힘
Why not use a map here?부드럽게Would a map work here? We look items up by id in the loop.
Why not…?은 글에서 “왜 안 했냐”로 읽히기도 합니다. 근거를 한 줄 붙입니다.
코멘트를 보내기 전에 두 가지만 확인하세요. 주어가 you인가, 이유가 한 줄 붙어 있는가.
받은 코멘트에 답할 때는 반영했다면 한 줄로 끝내고, 반영하지 않을 때는 이유와 바꿀 여지를 같이 적습니다.
- Good point. I'll do that in a follow-up PR.맞는 말씀이에요. 그건 후속 PR에서 하겠습니다.이번 PR 범위를 벗어날 때
- I'd rather keep this as is, since the list never has more than a few items. Happy to change it if you feel strongly.목록에 항목이 몇 개 이상 들어가는 일이 없어서 이대로 두고 싶습니다. 강하게 생각하시면 바꾸겠습니다.반영하지 않을 때
- LGTM once the token logging is removed.토큰 로깅만 빠지면 승인합니다.LGTM = looks good to me. 조건부 승인
04설명하는 글
PR 설명과 버그 리포트는 빈칸을 정해 두고 씁니다
PR 설명은 What, Why, How to test 세 칸(Out of scope는 덤)을 많이 쓰고, 버그 리포트는 Expected와 Actual을 나란히 놓습니다. 팀마다 템플릿이 다르지만 칸을 채우면 읽는 사람이 바로 판단합니다.
리뷰어는 PR을 열기 전에 설명 칸부터 읽습니다. “Fix bug”만 적혀 있으면 무엇이 바뀌었는지 코드를 읽어서 알아내야 합니다.
- Subject
- Retry failed uploads on network errors
WhatRetries a failed upload up to three times, with a short wait between attempts.
WhyUsers on a weak connection lost the whole upload after a single dropped request.
How to test1. Start uploading a large file.
2. Turn off Wi-Fi for a few seconds.
3. The upload should retry and finish.
Out of scopeMaking the retry count configurable. I'll open a separate PR for that.
Subject는 PR 제목입니다. Out of scope 한 줄은 “이것도 고쳐 달라”는 코멘트를 줄여 줍니다.
버그 리포트(이슈 티켓)도 흔히 쓰는 다섯 칸을 채우면 되묻는 일이 줄어듭니다. Expected와 Actual은 나란히 놓습니다.
| 칸 | 문장 | 하는 일 |
|---|---|---|
| Summary | Upload fails with a timeout on slow connections. | 무엇이 안 되는지 한 줄 |
| Steps to reproduce | 1. Open the upload page. 2. Throttle the network. 3. Upload a 50 MB file. | 같은 화면을 볼 수 있게 순서대로 |
| Expected | The upload retries and finishes. | 기대한 동작 |
| Actual | The upload stops at the first timeout and shows a generic error. | 실제로 일어난 일 |
| Environment | Staging, build 482. Happens every time. | 환경과 재현 빈도 |
“It doesn’t work.”만 쓰면 “What did you expect to happen?”부터 되묻게 됩니다. 버그인지 자신이 없으면 “Not sure if this is intended, but…”으로 시작하세요.
05장애·지연
장애나 지연은 지금 어느 단계인지와 다음 공지 시각을 먼저 씁니다
장애 공유는 지금이 어느 단계인지를 먼저 밝히고, 원인이나 복구 시각을 모르면 모른다고 쓴 뒤 다음 공지 시각을 약속합니다.
- Investigating문제를 알고 확인 중We're seeing failed uploads and are looking into it.
- Identified원인을 찾아 고치는 중We've identified the cause and are working on a fix.
- Monitoring조치 후 회복을 지켜보는 중A fix is in place. We're monitoring to confirm uploads are recovering.
- Resolved끝났고 후속 정리를 약속The issue is resolved. We'll share a postmortem by Friday.
- We don't have an ETA yet. Next update in 30 minutes.복구 예상 시각은 아직 없습니다. 30분 뒤에 다시 공유하겠습니다.ETA = estimated time of arrival, 여기서는 복구 예상 시각
- The impact is limited to uploads. Everything else is working normally.영향은 업로드에만 있습니다. 나머지는 정상입니다.영향 범위를 먼저 좁혀 줄 때
- We rolled back the release to mitigate the impact.영향을 줄이려고 릴리스를 되돌렸습니다.mitigate = 원인을 해결하기 전에 영향부터 줄이다
- Heads-up: this will slip to Thursday. The vendor API returns a different format than documented, so I'm reworking the parser.미리 알려 드립니다. 목요일로 밀릴 것 같습니다. 외부 업체 API가 문서와 다른 형식으로 응답해서 파서를 다시 짜고 있습니다.일정 지연. slip = 밀리다. 새 날짜와 이유를 한 번에
KEY LINE
The issue is mitigated, and we're still investigating the root cause.06막혔을 때
“막혔다”에서 끝내지 말고, 누가 무엇을 해 주면 풀리는지까지 씁니다
I’m blocked on 뒤에 막힌 대상을 쓰고 필요한 도움을 덧붙입니다. 모르는 것을 묻는 글은 상황, 해 본 것, 묻는 것 세 줄이면 됩니다.
“I’m blocked”는 남 탓이 아니라 스탠드업과 스레드에서 흔히 쓰는 사실 보고입니다.
막혔다고 알리고 도움을 받는 대화
How's the migration going?마이그레이션은 어떻게 돼 가요?
Mostly done, but I'm blocked on staging access. I asked in the infra channel yesterday and haven't heard back.거의 끝났는데 스테이징 접근 권한 때문에 막혔어요. 어제 인프라 채널에 물었는데 답이 없네요.
That's Tom's area. I'll ping him.그건 톰 담당이에요. 제가 메시지 넣어 볼게요.
막혔다는 말에는 어디에서 얼마나 기다렸는지가 같이 있어야 합니다.
KEY LINE
I'm blocked on staging access. Could you point me to who owns it?모르는 것을 묻는 글도 Hi만 보내 놓고 기다리지 말고, 상황과 해 본 것과 묻는 것을 한꺼번에 보냅니다.
- I'm trying to upload files over 50 MB, but the request times out.50MB가 넘는 파일을 올리려는데 요청이 타임아웃됩니다.1. 상황
- I already tried raising the timeout to 60 seconds, with no luck.타임아웃을 60초로 올려 봤는데 소용이 없었습니다.2. 해 본 것
- Is there a size limit on the proxy that I'm missing?제가 놓치고 있는 프록시 크기 제한이 있을까요?3. 묻는 것
- That did it. Thanks.그거였네요. 고맙습니다.해결된 뒤 스레드에 남기는 한 줄
진단 도구가 아니라 평소 쓰는 글을 스스로 점검하는 목록입니다. 해당하는 것만 눌러 보세요.
내 영어 글쓰기 습관 점검
0 / 6
해당하는 항목을 눌러 체크해 보세요.
프렌글은 원어민 강사와 Google Meet로 1:1로 말하는 수업을 하고, 수업이 없는 날에는 전담 코치가 매일 카카오톡으로 질문을 보내 답한 문장을 고쳐 줍니다.
끝다음 연습으로
이번 주에는 PR 설명 틀 하나를 만들어 두기
이번 주에 올릴 PR이 있다면 설명 칸에 What / Why / How to test 세 줄을 영어로 먼저 적어 보세요. 한 번 써 둔 틀을 복사해 두면 다음 PR부터는 빈칸만 채우면 됩니다.
QFAQ
자주 묻는 질문
Q.개발자는 영어 회화보다 영어 글쓰기를 먼저 연습해야 하나요?
해외 팀과 일한다면 글로 쓰는 장면이 먼저 닥치는 경우가 많습니다. 코드 리뷰, PR 설명, 이슈 티켓은 틀을 갖춘 경우가 많아서 미리 준비하기 좋습니다. 스탠드업처럼 말로 하는 자리도 있으니 짧은 문장 몇 개는 입에 붙여 두세요.
Q.코드 리뷰에서 nit은 무슨 뜻인가요?
nit은 nitpick(사소한 트집)의 줄임말로, 고치지 않아도 병합을 막지 않는 사소한 지적에 붙입니다. 팀마다 접두어와 약속이 다르니 처음에는 팀 문서나 기존 코멘트를 보고 맞추세요.
Q.영어 코드 리뷰 코멘트가 무례하게 읽히지 않으려면 어떻게 쓰나요?
짧게 쓰는 것 자체는 문제가 아닙니다. 사람 대신 코드를 주어로 쓰고, 결론만 던지지 말고 이유를 한 줄 붙이세요. 가볍게 제안하고 싶을 때는 Would X work here?처럼 선택지의 형태로 씁니다.
Q.영어로 장애나 일정 지연을 알릴 때 무엇부터 적어야 하나요?
지금 어느 단계인지, 영향이 어디까지인지, 다음 공지가 언제인지를 먼저 적습니다. 원인이나 복구 시각을 모르면 모른다고 쓰고 다음 공지 시각을 약속하면 됩니다.