| 젠 토토 : 문서 : 9.6 : 젠 토토 | |||
|---|---|---|---|
| PostgreSQL : 문서 : 9.6 : 서버 내 토토 캔보고 | 스포츠 토토 : 문서 : 9.6 : 스포츠 토토 코딩 규칙 | 52장. PostgreSQL 코딩 규칙 | PostgreSQL : 문서 : 9.6 : 기타 코딩 토토 베이 |
이 스타일 가이드는 생성된 모든 토토 캔 전반에 걸쳐 일관되고 사용자 친화적인 스타일을 유지하기 위해 제공됩니다.PostgreSQL.
기본 메시지는 짧고 사실이어야 하며 특정 함수 이름과 같은 구현 세부정보에 대한 언급을 피해야 합니다."짧음"의미"정상적인 조건에서는 한 줄에 맞아야 합니다". 기본 토토 캔를 짧게 유지해야 하거나 실패한 특정 시스템 호출과 같은 구현 세부 사항을 언급해야 할 경우 세부 토토 캔를 사용하세요. 기본 토토 캔와 세부 토토 캔는 모두 사실이어야 합니다. 특히 제안이 항상 적용 가능하지 않을 수 있는 경우 문제를 해결하기 위해 수행할 작업에 대한 제안을 보려면 힌트 토토 캔를 사용하세요.
예를 들어 다음 대신:
IpcMemoryCreate: shmget(키=%d, 크기=%u, 0%o) 실패: %m (기본적으로 힌트인 긴 부록도 포함)
쓰기:
기본: 공유 메모리 세그먼트를 생성할 수 없습니다: %m 세부 정보: 실패한 syscall은 shmget(key=%d, size=%u, 0%o)입니다. 힌트: 부록
이유: 기본 메시지를 짧게 유지하면 요점을 전달하는 데 도움이 되며 오류 메시지에는 한 줄이면 충분하다는 가정 하에 클라이언트가 화면 공간을 배치할 수 있습니다. 세부 정보 및 힌트 메시지는 자세한 정보 표시 모드 또는 팝업 오류 세부 정보 창으로 이전될 수 있습니다. 또한 세부 정보와 힌트는 일반적으로 공간을 절약하기 위해 서버 로그에서 표시되지 않습니다. 사용자가 세부정보를 알 것으로 예상되지 않으므로 구현 세부정보에 대한 참조는 피하는 것이 가장 좋습니다.
토토 캔 텍스트의 형식화에 대해 특정 가정을 두지 마십시오. 클라이언트와 서버 로그가 자신의 필요에 맞게 줄을 줄바꿈할 것으로 예상합니다. 긴 토토 캔에서는 줄 바꿈 문자(\n)를 사용하여 제안된 단락 구분을 나타낼 수 있습니다. 줄바꿈으로 토토 캔를 끝내지 마세요. 탭이나 기타 서식 문자를 사용하지 마세요. (오류 컨텍스트 표시에서는 함수 호출과 같은 별도의 컨텍스트 수준에 줄 바꿈이 자동으로 추가됩니다.)
이유: 토토 캔가 반드시 터미널 유형 디스플레이에 표시되는 것은 아닙니다. GUI 디스플레이 또는 브라우저에서는 이러한 형식 지정 지침이 기껏해야 무시됩니다.
영어 텍스트는 인용이 적절할 경우 큰따옴표를 사용해야 합니다. 다른 언어로 된 텍스트는 다른 프로그램의 출판 관습 및 컴퓨터 출력과 일치하는 한 종류의 인용문을 일관되게 사용해야 합니다.
이유: 작은 따옴표 대신 큰 따옴표를 선택하는 것은 다소 임의적이지만 선호되는 사용 경향이 있습니다. 어떤 사람들은 SQL 규칙에 따라 객체 유형에 따라 따옴표 종류를 선택하도록 제안했습니다(즉, 문자열은 작은 따옴표로 묶고 식별자는 큰 따옴표로 묶음). 그러나 이는 많은 사용자가 익숙하지도 않은 언어 내부의 기술적 문제이며, 다른 종류의 인용 용어로 확장되지 않고, 다른 언어로 번역되지도 않으며, 꽤 무의미합니다.
파일 이름, 사용자 제공 식별자 및 단어가 포함될 수 있는 기타 변수를 구분하려면 항상 따옴표를 사용하십시오. 단어를 포함하지 않는 변수(예: 연산자 이름)를 마크업하는 데 사용하지 마세요.
백엔드에는 필요에 따라 자체 출력을 큰따옴표로 묶는 함수가 있습니다(예:format_type_be()). 그러한 함수의 출력 주위에 추가 따옴표를 붙이지 마십시오.
이유: 개체는 토토 캔에 포함될 때 모호성을 유발하는 이름을 가질 수 있습니다. 플러그인 이름이 시작하고 끝나는 위치를 일관되게 표시하십시오. 하지만 불필요하거나 중복된 따옴표로 토토 캔를 복잡하게 만들지 마세요.
기본 오류 메시지와 세부정보/힌트 메시지의 규칙은 다릅니다.
주요 오류 토토 캔: 첫 글자를 대문자로 쓰지 마십시오. 토토 캔를 마침표로 끝내지 마세요. 느낌표로 토토 캔를 끝낼 생각은 하지 마세요.
세부사항 및 힌트 토토 캔: 완전한 문장을 사용하고 각 문장은 마침표로 끝납니다. 문장의 첫 단어를 대문자로 표기하세요. 다른 문장이 뒤에 오면 마침표 뒤에 공백 두 개를 넣으십시오(영어 텍스트의 경우, 다른 언어에서는 부적절할 수 있음).
오류 컨텍스트 문자열: 첫 글자를 대문자로 쓰지 말고 마침표로 문자열을 끝내지 마십시오. 컨텍스트 문자열은 일반적으로 완전한 문장이 아니어야 합니다.
이유: 구두점을 피하면 클라이언트 애플리케이션이 다양한 문법적 맥락에 토토 캔를 삽입하기가 더 쉬워집니다. 어쨌든 기본 토토 캔는 문법적으로 완전한 문장이 아닌 경우가 많습니다. (그리고 두 개 이상의 문장이 될 정도로 길면 기본 부분과 세부 부분으로 나누어야 합니다.) 그러나 세부 토토 캔와 힌트 토토 캔는 더 길며 여러 문장을 포함해야 할 수도 있습니다. 일관성을 위해 문장이 하나만 있는 경우에도 완전한 문장 스타일을 따라야 합니다.
주요 오류 토토 캔의 첫 글자를 포함하여 토토 캔 문구에 소문자를 사용하십시오. SQL 명령과 키워드가 토토 캔에 나타나면 대문자를 사용하세요.
이유: 일부 토토 캔는 완전한 문장이고 일부는 그렇지 않기 때문에 모든 것을 이 방법으로 더욱 일관되게 보이게 만드는 것이 더 쉽습니다.
활성태를 사용하세요. 연기주제가 있을 때는 완전한 문장을 사용하세요("A는 B를 할 수 없었습니다"). 주제가 프로그램 자체인 경우 주제 없이 텔레그램 스타일을 사용하십시오. 사용하지 마세요"나"프로그램용.
이유: 이 프로그램은 인간이 아닙니다. 다른 척하지 마세요.
어떤 일을 하려는 시도가 실패했지만 다음 번에는 성공할 수 있는 경우(아마도 문제를 해결한 후) 과거 시제를 사용하십시오. 실패가 확실히 영구적이라면 현재 시제를 사용하세요.
다음 형식의 문장 간에는 의미론적으로 중요한 차이가 있습니다.
"%s" 파일을 열 수 없습니다: %m
그리고:
"%s" 파일을 열 수 없습니다
첫 번째는 파일을 열려는 시도가 실패했음을 의미합니다. 메시지는 다음과 같은 이유를 제공해야 합니다."디스크가 가득 참"또는"파일이 존재하지 않습니다". 다음에 디스크가 더 이상 가득 차지 않거나 문제의 파일이 존재할 수 있으므로 과거 시제가 적절합니다.
두 번째 형식은 명명된 파일을 여는 기능이 프로그램에 전혀 존재하지 않거나 개념적으로 불가능하다는 것을 나타냅니다. 상태가 무한정 지속되므로 현재 시제가 적절합니다.
이유: 물론 일반 사용자는 토토 캔의 시제만으로는 훌륭한 결론을 도출할 수 없지만 언어는 문법을 제공하므로 올바르게 사용해야 합니다.
객체의 이름을 인용할 때, 그것이 어떤 종류의 객체인지 명시하십시오.
근거: 그렇지 않으면 아무도 무엇을 알지 못할 것입니다."foo.bar.baz"을 참조합니다.
대괄호는 (1) 명령 개요에서 선택적 인수를 표시하거나 (2) 배열 아래 첨자를 표시하는 데에만 사용됩니다.
이유: 다른 것은 널리 알려진 관례적인 사용법에 해당하지 않으며 사람들을 혼란스럽게 할 것입니다.
메시지에 다른 곳에서 생성된 텍스트가 포함되어 있으면 다음 스타일로 포함하세요.
%s 파일을 열 수 없습니다: %m
이유: 이를 하나의 매끄러운 문장에 붙여넣기 위해 가능한 모든 오류 코드를 설명하는 것은 어려울 수 있으므로 일종의 구두점이 필요합니다. 포함된 텍스트를 괄호 안에 넣는 것도 제안되었지만, 종종 그렇듯이 포함된 텍스트가 토토 캔의 가장 중요한 부분이 될 가능성이 높다면 부자연스럽습니다.
토토 캔에는 항상 오류가 발생한 이유가 명시되어야 합니다. 예를 들면:
나쁜: %s 파일을 열 수 없습니다. 더 나은 점: %s 파일을 열 수 없습니다(I/O 실패).
이유가 알려지지 않은 경우 코드를 수정하는 것이 좋습니다.
오류 텍스트에 보고 루틴의 이름을 포함하지 마십시오. 필요할 때 이를 알아낼 수 있는 다른 메커니즘이 있지만 대부분의 사용자에게는 도움이 되지 않는 정보입니다. 오류 텍스트가 함수 이름 없이는 이해가 되지 않으면 다시 작성하세요.
나쁜: pg_atoi: "z"에 오류가 있습니다: "z"를 구문 분석할 수 없습니다. 더 좋음: 정수에 대한 잘못된 입력 구문: "z"
호출된 함수 이름을 언급하지 마세요. 대신 코드가 무엇을 하려고 했는지 말해 보세요.
나쁜: open() 실패: %m 나은 점: %s 파일을 열 수 없습니다: %m
정말 필요하다고 생각되면 세부 메시지에 시스템 호출을 언급하세요. (어떤 경우에는 시스템 호출에 전달된 실제 값을 제공하는 것이 세부 메시지에 대한 적절한 정보일 수 있습니다.)
이유: 사용자는 이러한 모든 기능이 무엇을 하는지 모릅니다.
불가능합니다. "불가능"은 거의 수동태입니다. 더 나은 사용"할 수 없습니다"또는"할 수 없습니다", 적절하게.
나쁜.다음과 같은 오류 메시지"나쁜 결과"지능적으로 해석하기가 정말 어렵습니다. 결과가 왜 나오는지 쓰는 것이 좋습니다."나쁜"예:"잘못된 형식".
불법입니다. "불법"법 위반을 의미하며 나머지는 다음과 같습니다."잘못됨". 더 좋은 점은 왜 유효하지 않은지 말씀해 주시는 것입니다.
알 수 없음.피하려고 노력하세요"알 수 없음". 고려하세요"오류: 알 수 없는 응답". 응답이 무엇인지 모른다면 그것이 오류라는 것을 어떻게 알 수 있나요?"인식되지 않음"종종 더 나은 선택입니다. 또한 불만이 제기되는 가치도 반드시 포함하세요.
나쁨: 알 수 없는 노드 유형 더 좋음: 인식할 수 없는 노드 유형: 42
찾기 대 존재함.프로그램이 리소스를 찾기 위해 중요하지 않은 알고리즘(예: 경로 검색)을 사용하고 해당 알고리즘이 실패하는 경우 프로그램이 실패했다고 말하는 것이 타당합니다."찾기"자원. 반면에 리소스의 예상 위치가 알려져 있지만 프로그램이 거기에 액세스할 수 없는 경우 리소스가 액세스할 수 없다고 말합니다."존재". 사용"찾기"이 경우에는 약해 보이고 문제를 혼란스럽게 합니다.
5월 vs. 수 vs. 힘. "5월"허가를 제안하며(예: "내 갈퀴를 빌려도 됩니다.") 문서나 오류 메시지에서는 거의 사용되지 않습니다."할 수 있다"능력을 제안합니다(예: "나는 그 통나무를 들어올릴 수 있습니다.") 및"아마도"가능성을 제안합니다(예: "오늘 비가 올 수도 있습니다."). 적절한 단어를 사용하면 의미가 명확해지고 번역에 도움이 됩니다.
축소.수축을 피하세요."할 수 없습니다"; 사용"할 수 없습니다"대신.
음수가 아닙니다.피하세요"음수가 아닌"0을 허용하는지 여부가 모호하기 때문입니다. 사용하는 것이 더 좋습니다"0보다 큼"또는"0보다 크거나 같음".
오류 메시지 텍스트를 다른 언어로 번역해야 한다는 점을 명심하십시오. 다음 지침을 따르세요.섹션 53.2.2번역가의 삶을 힘들게 하지 않기 위해.