구글에서 제안하는 오류 메시지 작성 방법

잘 작성된 오류 메시지

: 실행 가능

: 좋은 사용자 경험 제공

: 적은 작업량, 신속한 문제 해결

: 사용자가 스스로 다음 행동을 취할 수 있음

 

 

 

 

오류 처리 규칙

- 조용히 실패하지 않을 것

: 실패를 묵인하면 문제의 원인을 찾을 수 없다

: 때문에 오류를 꼭 알릴 수 있어야 한다

 

- 오류는 즉시 알릴 것

: 오류를 붙잡고 있다가 나중에 발생시키면 오류를 추적하고 디버깅 하는 비용이 크게 증가한다.

: 오류가 발생하는 지점에서 바로 알림을 진행하자

 

- 자세한 원인을 명시할 것

: "500: 서버에서 예외가 발생했습니다"와 같은 메시지는 원인을 파악할 수 없다

: 보안상 문제가 되지 않을 정도로만 사용자가 다음 행동을 결정할 수 있도록 컨텍스트를 제공하도록 하자

 

- 에러코드를 기록할 것

: 가능하면 모든 에러코드에 대해 문서화를 진행해두면 좋다

 

- 프로그래밍 언어 가이드를 따를 것

Google C++ Style Guide

 

Google Java Style Guide

styleguide

Google JavaScript Style Guide

 

 

 

 

 

 

오류 메시지 작성법

- 오류 원인 전달

❌ Not recommended
유효하지 않은 디렉토리 입니다.

✅ Recommended
지정된 디렉토리가 존재하지만 쓰기(Write)를 할 수 없습니다.
디렉토리에 파일을 추가하려면 디렉토리 쓰기(Write) 권한이 있어야 합니다.
[쓰기 권한을 부여하는 방법 설명]

 

- 올바르지 않은 입력 전달

❌ Not recommended
잘못된 우편번호 입니다.

✅ Recommended
우편번호는 반드시 5자리 혹은 6자리 숫자로 이루어져야 합니다. 입력된 우편번호 (1234567) 는 7자리 입니다.

 

- 요구 사항, 제약 사항 명시

❌ Not recommended
프로필 이미지의 용량이 너무 큽니다.

✅ Recommended
프로필 이미지의 크기(14MB)가 제한(10MB)를 초과합니다. [이미지 크기를 줄일 수 있는 방법 설명]

 

- 해결 방법과 예시 제공

❌ Not recommended
현재 버전의 앱은 더 이상 지원되지 않습니다.

✅ Recommended
현재 버전의 앱은 더 이상 지원되지 않습니다. "앱 업데이트" 버튼을 클릭해서 업데이트를 진행해주세요.

 

- 간결하고 명확하게

❌ Not recommended
리소스를 찾거나 구별할 수 없습니다. 선택한 항목이 클러스터에 존재하지 않습니다. [리소스를 찾는 방법에 대한 설명]

✅ Recommended
<이름> 리소스가 <이름> 클러스터에 없습니다. [리소스를 찾는 방법에 대한 설명]

 

- 이중 부정 금지

❌ Not recommended
경로에 대한 읽기 권한은 운영체제가 액세스를 금지하는 것을 방지합니다.

✅ Recommended
경로에 대한 읽기 권한이 있으면 누구나 액세스 가능합니다. 개별로 액세스를 제한하는 방법은 아래 설명을 참조하십시오 [...]

 

- 사용자를 위한 단어 선택

❌ Not recommended
서버의 CPU 사용량이 92%에 달해 클라이언트의 요청을 제거했습니다. 5분 후 다시 시도하십시오.

✅ Recommended
현재 이용고객이 많아 일시적으로 구매를 완료할 수 없습니다. 5분 후 다시 시도해주세요.

 

- 일관된 용어 사용

❌ Not recommended
localhost:3306 애플리케이션에 연결할 수 없습니다. MySQL 이 실행 중인지 확인이 필요합니다.

✅ Recommended
localhost:3306 MySQL 에 연결할 수 없습니다. MySQL 이 실행 중인지 확인이 필요합니다.

 

 

 

 

 

 

가독성 높이기

- 상세 문서 링크

❌ Not recommended
게시물에 안전하지 않은 정보가 포함되어 있습니다.

✅ Recommended
게시물에 안전하지 않은 정보가 포함되어 있습니다. 자세한 사항은 <docs link> 를 확인해주세요.

 

- 점진적인 메시지 전달

❌ Not recommended
TextField widgets require a Material widget ancestor, 
but none were located. In material design, most widgets 
are conceptually “printed” on a sheet of material. 
To introduce a Material widget, either directly include one 
or use a widget that contains a material itself.


✅  Recommended
TextField widgets require a Material widget ancestor, but none were located.

...(Click to see more.)

In material design, most widgets are conceptually "printed" on a sheet of material. 
To introduce a Material widget, either directly include one 
or use a widget that contains a material itself.

 

- 오류와 가까운 곳에 메시지 배치

❌ Not recommended
1: program figure_1;
2: Grade = integer;
3: var
4. print("Hello")
Use ':' instead of '=' when declaring a variable.


✅  Recommended
1: program figure_1;
2: Grade = integer; 
---------^ Syntax Error
Use ':' instead of '=' when declaring a variable.
3: var
4. print("Hello")

 

 

 

 

 

 

 

올바른 어조 사용

- 긍정적인 어조 사용

❌ Not recommended
이름을 입력하지 않았습니다.

✅  Recommended
이름을 입력하세요.

 

 

 

 

 

 

백엔드 엔지니어를 위한 추가 지침

- 에러코드를 제공하라

❌ Not recommended
오류: 이 버킷을 이미 소유하고 있습니다. 목록에서 다른 이름을 선택합니다.

✅  Recommended

 

- 관련 에러 이슈 문서 포함

❌ Not recommended
{ 
    "error" : "Bad Request - Request is missing a required parameter: 
        -collection_name. Update parameter and resubmit.
}
 
✅  Recommended
{ 
    "error" : "Bad Request - Request is missing a required parameter: 
        -collection_name. Update parameter and resubmit. 
        Issue Reference Number BR0x0071"
}

 

 

 

 

 

 

 

Reference

구글에서 제안하는 오류 메세지 작성법