| PostgreSQL 9.3.25 문서 | ||||
|---|---|---|---|---|
| 이전 | 토토 핫 : 문서 : 9.3 : 토토 핫 코딩 규칙 | 49장. PostgreSQL 코딩 규칙 | 토토 : 문서 : 9.3 : 모국어 지원 | |
이 스타일 가이드는 모든 토토 핫 전반에 걸쳐 일관되고 사용자 친화적인 스타일 생성자PostgreSQL.
기본 토토 핫는 짧고 사실적이어야 하며 피해야 합니다. 특정 기능 등 구현 세부 사항 참조 이름."짧음"의미"정상적인 조건에서는 한 줄에 맞아야 합니다". 기본 메시지를 짧게 유지하려면 필요한 경우 세부 메시지를 사용하세요. 또는 다음과 같은 구현 세부 사항을 언급할 필요가 있다고 생각하는 경우 실패한 특정 시스템 호출. 기본 및 세부 정보 모두 메시지는 사실이어야 합니다. 제안사항에 힌트 메시지 사용 문제를 해결하기 위해 무엇을 해야 하는지에 대해, 특히 제안이 있는 경우 항상 적용 가능한 것은 아닙니다.
예를 들어 다음 대신:
IpcMemoryCreate: shmget(키=%d, 크기=%u, 0%o) 실패: %m (기본적으로 힌트인 긴 부록도 포함)
쓰기:
기본: 공유 메모리 세그먼트를 생성할 수 없습니다: %m 세부 정보: 실패한 syscall은 shmget(key=%d, size=%u, 0%o)입니다. 힌트: 부록
이유: 기본 메시지를 짧게 유지하는 것은 메시지를 유지하는 데 도움이 됩니다. 클라이언트가 가정에 따라 화면 공간을 배치할 수 있도록 합니다. 오류 메시지에는 한 줄이면 충분합니다. 세부정보 및 힌트 메시지는 장황한 모드로 전환되거나 팝업으로 표시될 수 있습니다. 오류 세부정보 창입니다. 또한 세부사항과 힌트는 일반적으로 공간을 절약하기 위해 서버 로그에서 표시되지 않습니다. 참조 사용자가 모르기 때문에 구현 세부 사항은 피하는 것이 가장 좋습니다. 어쨌든 자세한 내용은요.
형식 지정에 대해 특정 가정을 넣지 마십시오. 메시지 텍스트. 클라이언트와 서버 로그가 다음 행으로 줄 바꿈될 것으로 예상합니다. 자신의 필요에 맞게. 긴 메시지에서는 개행 문자(\n)를 사용할 수 있습니다. 제안된 단락 나누기를 나타내는 데 사용됩니다. 메시지를 끝내지 마세요 개행 문자로. 탭이나 기타 서식 문자를 사용하지 마세요. (에서 오류 컨텍스트가 표시되고 줄바꿈이 자동으로 추가됩니다. 함수 호출과 같은 별도의 컨텍스트 수준.)
이유: 메시지가 반드시 표시되는 것은 아닙니다. 터미널형 디스플레이. GUI 디스플레이 또는 브라우저에서는 다음을 수행합니다. 형식 지정 지침은 기껏해야 무시됩니다.
영어 텍스트는 인용할 때 큰따옴표를 사용해야 합니다. 적절하다. 다른 언어의 텍스트는 일관되게 다음 중 하나를 사용해야 합니다. 출판 관습에 부합하는 인용문과 다른 프로그램의 컴퓨터 출력.
이유: 작은 따옴표보다 큰 따옴표를 선택하는 것은 다음과 같습니다. 다소 임의적이지만 선호되는 용도로 사용되는 경향이 있습니다. 일부는 유형에 따라 인용문 종류를 선택하는 것이 좋습니다. SQL 규칙에 따른 객체(즉, 작은따옴표로 묶인 문자열, 식별자는 큰따옴표로 묶음). 그러나 이것은 언어 내부적이다. 많은 사용자가 익숙하지도 않은 기술적인 문제는 다른 종류의 인용 용어로 확장되지만 다른 용어로 번역되지는 않습니다. 언어도 있고 그것도 꽤 무의미해요.
파일 이름을 구분하려면 항상 따옴표를 사용하세요. 사용자 제공 식별자 및 단어를 포함할 수 있는 기타 변수. 하지 마십시오 단어를 포함하지 않는 변수를 마크업하는 데 사용합니다(예: 예, 연산자 이름).
백엔드에는 큰따옴표로 묶는 함수가 있습니다.
필요에 따라 자체 출력(예:format_type_be()). 추가 따옴표를 넣지 마십시오
그러한 함수의 출력 주위에.
이유: 객체는 다음과 같은 경우 모호함을 만드는 이름을 가질 수 있습니다. 메시지에 포함됩니다. 어디에 있는지 표시하는 데 일관성을 유지하세요. 플러그인 이름이 시작되고 끝납니다. 하지만 메시지를 복잡하게 만들지 마세요. 불필요하거나 중복된 따옴표.
기본 오류 메시지와 오류 메시지에 대한 규칙은 다릅니다. 세부정보/힌트 메시지:
주요 오류 토토 핫: 첫 글자를 대문자로 쓰지 마십시오. 마 토토 핫를 마침표로 끝내지 마세요. 끝낼 생각도 하지 마세요. 느낌표가 있는 토토 핫입니다.
세부사항 및 힌트 토토 핫: 완전한 문장을 사용하고 각 문장을 끝내십시오. 마침표가 있습니다. 문장의 첫 단어를 대문자로 표기하세요. 2개 넣어 다른 문장이 뒤따르면 마침표 뒤 공백(영어의 경우) 텍스트; 다른 언어에서는 부적절할 수 있습니다.)
오류 컨텍스트 문자열: 첫 글자를 대문자로 쓰지 말고 다음을 수행하십시오. 문자열을 마침표로 끝내지 마세요. 컨텍스트 문자열은 일반적으로 완전한 문장이 아니어야 합니다.
이유: 구두점을 피하면 클라이언트가 더 쉽게 작업할 수 있습니다. 다양한 문법에 메시지를 삽입하는 애플리케이션 컨텍스트. 기본 메시지가 문법적으로 완전하지 않은 경우가 많습니다. 어쨌든 문장. (그리고 둘 이상이 될 만큼 길다면 문장에서는 기본 부분과 세부 부분으로 나누어야 합니다.) 그러나 세부 정보 및 힌트 메시지는 더 길기 때문에 여러 문장을 포함하세요. 일관성을 위해 다음을 따라야 합니다. 문장이 하나만 있어도 완전한 문장 스타일입니다.
첫 글자를 포함하여 토토 핫 문구에 소문자를 사용하세요. 주요 오류 토토 핫 중 하나입니다. 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
찾기 대 존재함.프로그램이 중요하지 않은 것을 사용하는 경우 리소스를 찾는 알고리즘(예: 경로 검색) 알고리즘이 실패하면 프로그램이 실패했다고 말하는 것이 타당합니다."찾기"자원. 만약, 반면에 한편, 리소스의 예상 위치는 알려져 있지만 프로그램이 거기에 액세스할 수 없으면 리소스에 액세스할 수 없다고 말합니다."존재". 사용"찾기"이 경우에는 약하게 들리고 혼란스럽습니다. 문제.
메이 vs. 캔 vs. 마이트. "5월"허가를 제안하고(예: "내 갈퀴를 빌려도 됩니다.") 문서나 오류 메시지에서는 거의 사용되지 않습니다."할 수 있다"능력을 제안합니다(예: "나는 그것을 들어 올릴 수 있습니다 로그.") 및"아마도"가능성을 제안합니다 (예: "오늘은 비가 올 수도 있습니다.") 적절한 단어를 사용하면 명확해집니다. 의미를 부여하고 번역을 돕습니다.
축소.수축을 피하세요."할 수 없습니다"; 사용"할 수 없습니다"대신.
오류 메시지 텍스트를 다음 언어로 번역해야 한다는 점을 명심하십시오. 다른 언어. 다음 지침을 따르세요.섹션 50.2.2피하다 번역가의 삶을 어렵게 만듭니다.