| Documentação do PostgreSQL 8.0.0 | ||||
|---|---|---|---|---|
| Anterior | Início | Capítulo 44. Convenções de codificação do PostgreSQL | Fim | Próxima |
Este guia de estilo é oferecido na esperança de manter um estilo amigável e consistente entre todas as mensagens geradas pelo PostgreSQL.
A mensagem primária deve ser curta, baseada em fatos, evitando referências a detalhes da implementação, tal como nomes de funções específicas. "Curta" significa "deve caber em uma linha sob as condições normais". Se for necessário, deve ser utilizada uma mensagem de detalhe para manter a mensagem primária curta ou mencionar detalhes da implementação, como uma determinada chamada de sistema que falhou. Tanto a mensagem primária quanto a de detalhe devem ser baseadas em fatos. Deve ser utilizada uma mensagem de dica para fazer sugestões sobre o que fazer para corrigir o problema, especialmente se a sugestão não for sempre aplicável.
Por exemplo, em vez de
IpcMemoryCreate: shmget(chave=%d, tamanho=%u, 0%o) falhou: %m (mais um longo adendo que é basicamente uma dica)
deve ser escrito
Primária: não foi possível criar o segmento de memória compartilhada: %m Detalhe: A chamada do sistema que falhou foi shmget(chave=%d, tamanho=%u, 0%o). Dica: o adendo
Explicação: manter a mensagem primária curta ajuda mantê-la focada, e permite aos clientes organizar o espaço na tela assumindo que uma linha é suficiente para as mensagens de erro. As mensagens de detalhe e de dica podem ser relegadas para o modo verboso ou, talvez, colocadas em uma janela pop-up de detalhes de erro. Além disso, os detalhes e as dicas normalmente não devem estar presentes no log do servidor para economizar espaço. É melhor evitar as referências aos detalhes de implementação, uma vez que os usuários não o conhecem.
No texto das mensagens não se deve supor nada específico com relação à formatação. Deve-se esperar que os clientes e o log do servidor quebrem as linhas para ajustá-las às suas próprias necessidades. Nas mensagens longas podem ser utilizados caracteres de nova-linha (\n) para indicar quebras de linha sugeridas. A mensagem não deve terminar pelo caractere de nova-linha. Não devem ser utilizados tabulações ou outros caracteres de formatação (quando o contexto do erro é exibido, são adicionados caracteres de nova-linha, automaticamente, para separar os níveis do contexto, tal como chamadas a funções).
Explicação: As mensagens não são mostradas sempre em uma tela de terminal. Nas janelas de Interface Gráfica do Usuário e nos navegadores as instruções de formatação são, na melhor das hipóteses, ignoradas.
Nos textos em inglês são utilizadas aspas quando é feita uma transcrição. Os textos em outras línguas devem utilizar de forma consistente o sinal indicado pelas normas ortográficas vigentes, e a saída produzida por outros programas de computador.
Explicação: A escolha de aspas em vez de apóstrofos é um tanto arbitrária, mas há uma tendência em se preferir as aspas. Algumas pessoas sugerem escolher o tipo de acento conforme o tipo do objeto de acordo com as convenções da linguagem SQL (ou seja, cadeias de caracteres entre apóstrofos e identificadores entre aspas), mas esta é uma questão técnica interna da linguagem que muitos usuários não estão familiarizados com as mesmas, que não são aplicáveis a outros termos, que não pode ser traduzido para outros idiomas, e que não faz muito sentido também. [1] [2]
Sempre devem ser utilizadas aspas para delimitar nomes de arquivos, identificadores fornecidos pelos usuários e outras variáveis que possam conter palavras. Não devem ser utilizadas aspas em variáveis que não contenham palavras (por exemplo, nomes de operadores).
Existem funções no servidor que duplicam as aspas de suas próprias saídas conforme seja necessário (por exemplo, format_type_be()). Não devem ser colocadas aspas adicionais em torno da saída das funções deste tipo.
Explicação: Alguns objetos podem ter nomes que criam ambigüidade quando incorporados ao texto da mensagem. Deve ser indicado de forma consistente onde um nome incorporado começa e termina. A mensagem não deve ficar confusa devido a aspas duplicadas ou desnecessárias.
As regras são diferentes para as mensagens de erro primárias e para as mensagens de detalhe/dica:
Mensagens de erro primárias: a primeira letra não deve ser maiúscula. A mensagem não deve terminar por ponto. De forma alguma a mensagem pode terminar por um ponto de exclamação.
Mensagens de detalhe e de dica: Devem ser utilizados enunciados completos, terminados por ponto. A primeira letra de cada enunciado deve ser maiúscula.
Explicação: Evitar a pontuação torna mais fácil para o aplicativo cliente incorporar a mensagem em vários contextos gramaticais. Geralmente as mensagens primárias não são parágrafos completos (e se forem suficientemente longas para conter mais de um enunciado, devem ser divididas em primária e detalhe). Entretanto, as mensagens de detalhe e de dica são longas e podem precisar incluir vários enunciados. Por consistência devem seguir o estilo de parágrafo completo mesmo quando há apenas um enunciado.
Devem ser utilizadas letras minúsculas nas palavras da mensagem, inclusive a primeira letra da mensagem de erro primária. Devem ser utilizadas letras maiúsclas nos comandos SQL e nas palavras chave que aparecem nas mensagens.
Explicação: É mais fácil fazer que tudo pareça consistente desta forma, uma vez que algumas mensagens são enunciados completos e outras não.
Deve ser utilizada a voz ativa. Devem ser utilizados enunciados completos quando existir um agente da ação ("A não pode fazer B"). Deve ser utilizado um estilo tipo telegrama sem agente quando o agente é o próprio programa; não utilize "Eu" para o programa. [3] [4] [5]
Explicação: O programa não é humano. Não finja que seja.
Deve ser utilizado o passado quando uma tentativa de fazer algo falhou, mas talvez seja bem sucedida da próxima vez (talvez após a correção de algum problema). Deve ser utilizado o presente se provavelmente a falha é permanente.
Existe uma diferença de semântica que não é trivial entre as formas dos enunciados
não foi possível abrir o arquivo "%s": %m
e
não é possível abrir o arquivo "%s"
A primeira forma significa que uma tentativa de abrir o arquivo falhou. A mensagem deve informar o motivo, tal como "disco cheio" ou "arquivo não existe". O passado é apropriado porque da próxima vez o disco poderá não estar cheio, ou o arquivo em questão poderá existir.
A segunda forma indica que a funcionalidade de abrir o arquivo especificado não existe no programa, ou que é conceitualmente impossível. O presente é apropriado porque a condição permanecerá indefinidamente.
Explicação: De uma maneira geral o usuário médio não será capaz de chegar a uma conclusão apenas pelo tempo do verbo da mensagem, mas já que a língua portuguesa possui uma gramática esta deve ser utilizada da forma correta.
Quando o nome de um objeto é citado, deve ser informado o tipo do objeto.
Explicação: Senão ninguém vai saber a que "foo.bar.baz" se refere.
Os colchetes são utilizados apenas em: (1) nas sinopses dos comandos para indicar argumentos opcionais; ou (2) para indicar índice de matriz.
Explicação: Qualquer outra utilização não irá corresponder à utilização comum, só servindo para confundir as pessoas.
Quando uma mensagem inclui texto gerado em outro local, este texto deve ser incorporado usando o estilo:
não foi possível abrir o arquivo %s: %m
Explicação: É difícil levar em consideração todos os códigos de erro possíveis e colocá-los em um único enunciado corrido, portanto será necessário algum tipo de pontuação. Também foi sugerido colocar o texto incorporado entre parênteses, mas isto não é natural quando o texto incorporado pode ser a parte mais importante da mensagem, como geralmente é o caso.
As mensagens sempre devem informar o motivo pelo qual o erro ocorreu. Por exemplo:
RUIM: não foi possível abrir o arquivo %s MELHOR: não foi possível abrir o arquivo %s (falha de E/S)
Se o motivo for desconhecido, é melhor corrigir o código.
Não deve ser incluído no texto da mensagem o nome da rotina que está relatando o erro. Existem outros mecanismos para descobrir o nome quando for necessário, e para a maioria dos usuários esta informação não ajuda em nada. Se o texto da mensagem de erro não fizer sentido sem incluir o nome da função, então deve ser reescrito.
RUIM: pg_atoi: erro em "z": não foi possível analisar "z" MELHOR: sintaxe de entrada inválida para inteiro: "z"
Também deve ser evitado mencionar os nomes das funções chamadas; em vez disso, deve ser dito o que o código estava tentando fazer:
RUIM: open() falhou: %m MELHOR: não foi possível abrir o arquivo %s: %m
Se realmente for necessário mencionar a chamada de sistema, isto deve ser feito na mensagem de detalhe (Em alguns casos fornecer os verdadeiros valores passados para a chamada de sistema pode ser uma informação apropriada na mensagem de detalhe).
Explicação: Os usuários não sabem o que estas funções fazem.
Incapaz. "Incapaz" é quase uma passividade. É melhor utilizar "não é possível" ou "não foi possível", conforme for apropriado.
Ruim. As mensagens de erro do tipo "resultado ruim" são realmente difíceis de serem interpretadas de forma inteligente. É melhor escrever porque o resultado foi "ruim" como, por exemplo, "formato inválido".
Ilegal. "Ilegal" significa violação da lei, o resto é "inválido". Melhor ainda, deve ser dito porque é inválido.
Desconhecido. Deve-se tentar evitar o uso de "desconhecido". Considere o seguinte: "erro: resposta desconhecida". Se não se sabe qual é a resposta como se sabe que está errada? Geralmente "não reconhecido" é uma escolha melhor. Também deve ser mostrado o valor sobre o qual recai a reclamação.
RUIM: tipo de nó desconhecido MELHOR: tipo de nó não reconhecido: 42
Encontrar versus Existir. Se o programa utilizar um algoritmo não trivial para localizar um recurso (por exemplo, o caminho de procura), e o algoritmo não for bem-sucedido, é justo dizer que o programa não conseguiu "encontrar" o recurso. Se, por outro lado, o local esperado do recurso for conhecido, mas o programa não consegue acessar o recurso neste local, então deve ser dito que o recurso não "existe". Neste último caso, utilizar "encontrado" soa fraco e confunde o problema.
As palavras devem ser escritas por inteiro. Por exemplo, devem ser evitados:
espec
estat
prog
aut
fun
Explicação: Agindo assim melhora a consistência.
Deve-se ter em mente que os textos das mensagens de erro precisam ser traduzidos para outros idiomas. Devem ser seguidas as instruções contidas na Seção 45.2.2 para evitar tornar difícil a vida dos tradutores.
| [1] |
O apóstrofo — este sinal ('), que indica supressão de letras, tem hoje o seu emprego bastante reduzido. Usa-se para assinalar: a supressão de uma letra ou mais no verso, por exigência de metrificação; a apócope da vogal e em palavras compostas ligadas pela preposição de (estrela-d'alva); pronúncias populares ('tá); em derivados de nomes estrangeiros que já têm este sinal. Novo Manual de Português, Celso Pedro Luft, Editora Globo. (N. do T.) |
| [2] |
As aspas — as aspas ou vírgulas dobradas têm os seguintes empregos: assinalam transcrições textuais; realçam os nomes das obras de arte ou de publicações; caracterizam nomes, intitulativos, apelidos, etc.; marcam expressões, vocábulos, palavras, letras (substantivadas pelo contexto) citadas ou exemplificadas; separam neologismos, estrangeirismos ou quaisquer palavras estranhas ao contexto vernáculo. Novo Manual de Português, Celso Pedro Luft, Editora Globo. (N. do T.) |
| [3] |
voz ativa — forma em que o verbo se apresenta para normalmente indicar que a pessoa a que se refere é o agente da ação. A pessoa diz-se, neste caso, agente da ação verbal: Eu escrevo a carta, etc. Evanildo Bechara, Moderna Gramática Portuguesa, Edição Revista e Ampliada. (N. do T.) |
| [4] |
voz passiva — forma verbal que indica que a pessoa é o objeto da ação verbal. A pessoa, neste caso, diz-se paciente da ação verbal: A carta é escrita por mim, etc. Evanildo Bechara, Moderna Gramática Portuguesa, Edição Revista e Ampliada. (N. do T.) |
| [5] |
voz passiva e passividade — é preciso não confundir voz passiva e passividade. Voz é a forma especial em que se apresenta o verbo para indicar que a pessoa recebe a ação. Passividade é o fato da pessoa receber a ação verbal. Evanildo Bechara, Moderna Gramática Portuguesa, Edição Revista e Ampliada. (N. do T.) |
