43.3. Guide de style des messages d'erreurs

43.3.1. Ce qui va o�

Le message primaire devrait �tre court, factuel et �viter les r�f�rences aux d�tails d'ex�cution comme le nom de fonction sp�cifique. <<�Court�>> veut dire <<�devrait tenir sur une ligne dans des conditions normales�>>. Utilisez un message d�tail si n�cessaire pour garder le message primaire court ou si vous sentez le besoin de mentionner les d�tails de l'impl�mentation comme un appel syst�me particulier qui �choue. Les messages primaires et d�tails doivent �tre factuels. Utilisez un message conseil pour les suggestions � propos de quoi faire pour fixer le probl�me, sp�cialement si la suggestion ne pourrait pas toujours �tre applicable.

Par exemple, au lieu de

        IpcMemoryCreate: shmget(cl�=%d, taille=%u, 0%o) a �chou� : %m
        (plus un long suppl�ment qui est basiquement un conseil)

�crivez

        Primaire:    Ne peut pas cr�er un s�gment en m�moire partag�e : %m
        D�tail:      L'appel syst�me qui a �chou� �tait shmget(key=%d, size=%u, 0%o).
        Astuce:     Le suppl�ment

Raisonnement : garder le message primaire court aide � le garder au point et laisse les clients pr�senter un espace � l'�cran sur la supposition qu'une ligne est suffisante pour les messages d'erreurs. Les messages d�tails et conseils peuvent �tre rel�gu�s � un mode verbeux ou peut-�tre dans une fen�tre pop-up d�taillant l'erreur. De plus, les d�tails et les conseils devront normalement �tre supprim�s des traces du serveur pour gagner de l'espace. La r�f�rence aux d�tails d'impl�mentation est � �viter puisque les utilisateurs n'en connaissent de toute fa�on pas les d�tails.

43.3.2. Formatage

N'�mettez pas d'hypoth�ses sp�cifiques � propos du formatage dans les messages textes. Attendez-vous � ce que les clients et les traces du serveur enveloppent les lignes pour correspondre � leurs propres besoins. Dans les messages longs, les caract�res d'interlignes (\n) peuvent �tre utilis�s pour indiquer les coupures sugg�r�es d'un paragraphe. Ne terminez pas un message avec un caract�re d'interlignes. N'utilisez pas des tabulations ou d'autres caract�res de formatage. (Dans les affichages des contextes d'erreurs, les caract�res d'interlignes sont automatiquement ajout�s pour s�parer les niveaux d'un contexte comme dans les appels aux fonctions.)

Raisonnement : les messages ne sont pas n�cessairement affich�s dans un affichage de type terminal. Dans les interfaces graphiques ou les navigateurs, ces instructions de formatage sont, au mieux, ignor�es.

43.3.3. Guillemets

Les textes en anglais devraient utiliser des guillemets doubles quand la mise entre guillemets est appropri�e. Les textes dans les autres langues devraient uniform�ment employer un genre de guillemets qui est conforme aux coutumes de publication et � la sortie visuelle des autres programmes.

Raisonnement : le choix des guillemets doubles sur celui des guillemets simples est quelque peu arbitraire mais tend � �tre l'utilisation pr�f�r�e. Certains ont sugg�r� de choisir le type de guillemets en fonction du type d'objets des conventions SQL (notamment, les cha�nes de caract�res entre guillemets simples, les identifiants entre guillemets doubles). Mais ceci est un point technique � l'int�rieur du langage avec lequel beaucoup d'utilisateurs ne sont pas familiers ; les conventions SQL ne prennent pas en compte les autres genres de termes entre guillemets, ne sont pas traduites dans d'autres langues et manquent un peu de sens aussi.

43.3.4. Utilisation des guillemets

Utilisez toujours les guillemets pour d�limiter les noms de fichiers, les identifiants fournis par les utilisateurs et les autres variables qui peuvent contenir des mots. Ne les utilisez pas pour marquer des variables qui ne contiennent pas de mots (par exemple, les noms d'op�rateurs).

Il y a des fonctions au niveau du serveur qui vont, au besoin, mettre entre guillemets leur propre flux de sortie (par exemple, format_type_be()). Ne mettez pas de guillemets suppl�mentaires autour du flux de sortie de ce genre de fonctions.

Raisonnement : les objets peuvent avoir un nom qui cr�e une ambigu�t� une fois incorpor� dans un message. Soyez prudent en indiquant o� un nom commence et fini. Mais n'encombrez pas les messages avec des guillemets qui ne sont pas n�cessaires ou qui sont dupliqu�s.

43.3.5. Grammaire et ponctuation

Les r�gles sont diff�rentes pour les messages d'erreurs primaires et pour les messages d�tails/conseils :

Messages d'erreurs primaires : ne mettez pas en majuscule la premi�re lettre. Ne terminez pas un message avec un point. Ne pensez m�me pas � finir un message avec un point d'exclamation.

Messages d�tails et conseils : utilisez des phrases compl�tes et toutes termin�es par des points. Mettez en majuscule le premier mot des phrases.

Raisonnement : �viter la ponctuation rend plus facile, pour les applications clientes, l'int�gration du message dans des contextes grammaticaux vari�s. Souvent, les messages primaires ne sont de toute fa�on pas des phrases compl�tes. (Et s'ils sont assez longs pour �tre sur plusieurs phrases, ils devraient �tre divis�s en une partie primaire et une partie d�tail.) Cependant, les messages d�tails et conseils sont longs et peuvent avoir besoin d'inclure de nombreuses phrases. Pour la coh�rence, ils devraient suivre le style des phrases compl�tes m�me s'il y a seulement une phrase.

43.3.6. Majuscule contre minuscule

Utilisez les minuscules pour les mots d'un message, inclus la premi�re lettre d'un message d'erreur primaire. Utilisez les majuscules pour les commandes et les mots-cl� SQL s'ils apparaissent dans le message.

Raisonnement : il est plus facile de rendre toutes les choses plus coh�rentes au regard de cette fa�on, puisque certains messages sont des phrases compl�tes et d'autres non.

43.3.7. �viter la voix passive

Utilisez la voix active. Utilisez des phrases compl�tes quand il y a un sujet (<<�A ne peut pas faire B�>>). Utilisez le style t�l�gramme, sans sujet, si le sujet est le programme lui-m�me ; n'utilisez pas <<�Je�>> pour le programme.

Raisonnement : le programme n'est pas humain. Ne pr�tendez pas autre chose.

43.3.8. Pr�sent contre pass�

Utilisez le pass� si une tentative de faire quelque chose �chouait, mais pourrait peut-�tre r�ussir la prochaine fois (peut-�tre apr�s avoir corriger certains probl�mes). Utilisez le pr�sent si l'�chec est sans doute permanent.

Il y a une diff�rence s�mantique non triviale entre les phrases de la forme

        n'a pas pu ouvrir le fichier "%s": %m

et

        ne peut pas ouvrir le dossier "%s"

La premi�re forme signifie que la tentative d'ouverture du fichier a �chou�. Le message devrait donner une raison comme <<�disque plein�>> ou <<�le fichier n'existe pas�>>. Le pass� est appropri� parce que la prochaine fois le disque peut ne plus �tre plein ou le fichier en question peut exister.

La seconde forme indique que la fonctionnalit� d'ouvrir le fichier nomm� n'existe pas du tout dans le programme ou que c'est conceptuellement impossible. Le pr�sent est appropri� car la condition persistera ind�finiment.

Raisonnement : d'accord, l'utilisateur moyen ne sera pas capable de tirer de grandes conclusions simplement � partir du temps du message mais, puisque la langue nous fournit une grammaire, nous devons l'utiliser correctement.

43.3.9. Type de l'objet

En citant le nom d'un objet, sp�cifiez quel genre d'objet c'est.

Raisonnement : sinon personne ne saura ce qu'est <<�foo.bar.baz�>>.

43.3.10. Crochets

Les crochets sont uniquement utilis�s (1) dans les synopsis des commandes pour indiquer des arguments optionnels ou (2) pour indiquer l'indice inf�rieur d'un tableau.

Raisonnement : rien de ce qui ne correspond pas � l'utilisation habituelle, largement connue troublera les gens.

43.3.11. Assembler les messages d'erreurs

Quand un message inclut du texte qui est g�n�r� ailleurs, int�grez-le dans ce style :

        n'a pas pu ouvrir le fichier %s: %m

Raisonnement : il serait difficile d'expliquer tous les codes d'erreurs possibles pour coller ceci dans une unique phrase douce, ainsi une certaine forme de ponctuation est n�cessaire. Mettre le texte inclus entre parenth�ses a �t� �galement sugg�r�, mais ce n'est pas naturel si le texte inclus est susceptible d'�tre la partie la plus importante du message, comme c'est souvent le cas.

43.3.12. Raisons pour les erreurs

Les messages devraient toujours indiquer la raison pour laquelle une erreur s'est produite. Par exemple :

        MAUVAIS :  n'a pas pu ouvrir le fichier %s
        MEILLEUR : n'a pas pu ouvrir le fichier %s (�chec E/S)

Si aucune raison n'est connue, vous feriez mieux de corriger le code.

43.3.13. Nom des fonctions

N'incluez pas le nom de la routine de rapport dans le texte de l'erreur. Nous avons d'autres m�canismes pour trouver cela quand c'est n�cessaire et, pour la plupart des utilisateurs, ce n'est pas une information utile. Si le texte de l'erreur n'a plus beaucoup de sens sans le nom de la fonction, reformulez-le.

        MAUVAIS :  pg_atoi: erreur dans "z": ne peut pas analyser "z"
        MEILLEUR : syntaxe en entr�e invalide pour l'entier : "z"

�vitez de mentionner le nom des fonctions appel�es, au lieu de cela dites ce que le code essayait de faire :

        MAUVAIS :  ouvrir() a �chou� : %m
        MEILLEUR : n'a pas pu ouvrir le fichier %s: %m

Si cela semble vraiment n�cessaire, mentionnez l'appel syst�me dans le message d�tail. (Dans certains cas, fournir les valeurs r�elles pass�es � l'appel syst�me pourrait �tre une information appropri�e pour le message d�tail.)

Raisonnement : les utilisateurs ne savent pas tout ce que ces fonctions font.

43.3.14. Mots d�licats � �viter

        MAUVAIS :  type de nœud inconnu
        MEILLEUR : type de nœud non reconnu : 42

43.3.15. Orthographe appropri�e

Orthographiez les mots en entier. Par exemple, �vitez :

• spec (NdT : sp�cification)

• stats (NdT : statistiques)

• params (NdT : param�tres)

• auth (NdT : authentification)

• xact (NdT : transaction)

Raisonnement : cela am�liore la coh�rence.

43.3.16. Adaptation linguistique

Gardez � l'esprit que les textes des messages d'erreurs ont besoin d'�tre traduit en d'autres langues. Suivez les directives dans la Section 44.2.2 pour �viter de rendre la vie difficile aux traducteurs.