Conventions générales :
Les identifiants doivent toujours êtres écris en Anglais et s'approcher le plus possible d'un code écrit par un professionnel. Utilisez l'outil de traduction de Google ou un dictionnaire d'anglais pour traduire vos identifiants. Pensez toujours à le faire, car même si vos codes sont destinés à un public francophone, il se peut que des personnes étrangères s'y intéressent et les utilisent.
Evitez d'une manière générale les identifiants à rallonge ou encore trop court ou abstrait. L'identifiant doit permettre d'identifier clairement une variable ou un type, son utilisation, son but, son origine etc.
En pascal Objet, les identifiant sont écrit la plupart du temps en se qu'on appel "le dos de chameau" car chaque mots commence par une majuscule et la suite en minuscule, ce qui provoque des "bosses" dans leurs noms.
Exemple :
TListBox, TComboBox, FontSizeAera.
Les noms écrits avec une convention C,C++ (majuscule et underscore) sont réservé la plupart du temps aux types paramètres, aux méthodes écrites en assembleur, aux types devant d'abord être redéclarer ou suite à une traduction 1:1 d'un header C,C++.
Exemple :
WM_MOUSE_LEFT, VK_ESCAPE, function _DIV
Les conventions données ci-dessous, sont tirées directement ou établies à partir des codes émis par Borland et également les plus souvent rencontrées.
Notez bien que ces conventions sont uniquement faites pour harmoniser les écritures de codes entre développeurs permettant ainsi une meilleure compréhension entre tous et facilitant le travail en équipe.
Avec le développement d'Internet, il n'est plus rare de voir travailler ensemble des développeurs indépendants issus de différentes nations, il est donc nécessaire de respecter certaines normes.
Bien sur, elles restent facultatives, mais n'oubliez pas qu'elles ajouteront en qualités de finitions à vos codes, ce qui n'est pas négligeable.
A) Dénominateurs communs des identifiants :
Les dénominateurs communs peuvent être placés a l'intérieur du nom d'un identifiant ou comme suffixe la plupart du temps.
Servez vous de cette liste comme memo pour écrire vos identifiants, cette dernière n'en représente que quelques-uns ... ils en existent d'autre mais les citer tous serait trop long.
Ancien : [O, Old]
Buffer : [Bf, Buf,Buffer]
Booléen : [Bl, Bool]
Bouton : [Bt, Btn,Button]
Caractère : [C, Ch, Chr]
Carré : [Sq, Sqr, Square]
Chaine : [S, Str]
Cellule : [Cell]
Charger : [Load]
Colonne : [Cl, Col]
Compteur : [Cn, Cnt, Count]
Coordonnées : [X, Y, Z, L, R, Left, Right, Top, Bottom]
Couleur : [Cl, Col, Color]
Curseur : [Cr, Cur]
Dialogue : [Dlg, Dialog]
Dimensions : [W, Wh, Width, H, Ht, Height]
Donnée : [Dt, Dat, Data]
Double : [Dbl]
Enregistrement : [Rc, Rec]
Ensemble : [Set]
Entier : [I, Int]
Etendus : [E, Ext]
Flottant : [F, Flt, Float]
Générateur : [Gn, Gen, Generator]
Image : [Img, Gfx, Pic]
Information : [Nfo, Inf, Info]
Langage : [Ln, Lng, Lang, Language]
Ligne : [Rw, Row, Ln, Line]
Localisation : [Loc, Locate]
Maximum : [M, Mx, Max]
Message : [Msg, Messy, Message]
Minimum : [N, Mn, Min]
Objet : [O, Ob, Obj, Object]
Paramètre : [Prm, Param, Parameter]
Pixel : [Px, Pix, Pixel]
Point : [Pt, Pnt, Point]
Pointeur : [P, Ptr]
Position : [Ps, Pos]
Prime, Primaire : [Pm, Prim]
Rectangle : [Rt, Rct, Rect]
Registre : [Rg, Reg, Registry]
Ressource : [Rc, Res, Resource]
Sauver : [Sv, Save]
Son : [Sn, Snd, Sound]
Système : [Sys, System]
Tableau : [A, Ar, Arr, Array, Mtx, Matrix]
Texte : [Tx, Txt, Text]
B) Résumé des conventions des identifiants de types :
Tout types : [T]Nom
ensemble : [T]Nom[s (au pluriel)]
événement : [T]Nom[Event]
exception : [E]Nom[Error]
fonction : [T]Nom[Func]
interface : [I]Nom[Interface]
message : [T]Nom[Message]
objet : [T]Nom[Obj (facultatif)]
paramètre : NOM_TYPE ou Nom[Param, Parameter]
pointeur : [p, P]Nom
procédure : [T]Nom[Proc]
record : [T]Nom[Rec (facultatif)]
tableau dynamique : [T]Nom[DynArray (facultatif)]
tableau statique : [T]Nom[Tri, Quad][Array, Matrix, Vector]
C) Résumé des conventions des identifiants de variables :
argument de méthode : [A]Nom
autre variable : Nom[Dénominateurs communs]
constante : [C, Cs]Nom
variable privée de classe : [f]Nom
D) Résumé des conventions des identifiants de méthodes :
appel d'événement : [Do]Nom
conversion : NomTypeA[To]NomTypeB
création, constructeur : [Create]
détruire, destructeur : [Destroy]
définition de valeur : [Set]Nom
dessin quelconque : [Draw,Paint]Nom
effacer, vider : [Clear, Erase, Delete]Nom
événement : [On]Nom
initialiser : [Init, Initialize]Nom
libérer : [Free]Nom
message : [CM, WM, Msg]Nom
mettre a jours : [Upd, Update]Nom
retour de valeur : [Get]Nom
réinitialiser : [Reset]Nom
vérification d'état : [Is]Nom
E) Conventions Delphi et C++, comparaison :
Entre le Delphi et le C++ il existe une grosse différence pour écrire les identifiants. En Delphi on écrira toujours les identifiants en commençant par une majuscule chaque mot qui compose ce dernier.
Exemple :
TMonTypeAMoi
ProcedureQuiConvertisLesBitmapEnJPEG
En C++ on écrira plutôt les identifiants en majuscule avec un caractère Underscore (Shift+8) entre chaque mot qui le compose.
Exemple :
MON_TYPE_A_MOI
On peu bien sur utiliser l'une ou l'autre, voir les mélangées, le compilateur lui ne fait pas attention aux conventions d'écriture (mais il vérifie la syntaxe quand même ^^).
En Delphi, la convention d'écriture C++ est généralement utilisée pour les paramètres ou les valeurs constantes.
Exemple :
Type
TParamSound = $00..$7F;
Const
// Ecriture type C
PRM_SOUND_OFF : TParamSound = $00;
PRM_SOUND_ON : TParamSound = $01;
PRM_SOUND_MIX : TParamSound = $02;
// Ecriture type Delphi
PrmSoundOff = PRM_SOUND_OFF;
PrmSoundOn = PRM_SOUND_ON;
PrmSoundMix = PRM_SOUND_MIX;
F) Rappel d'écriture global des identifiants :
Pour n'importe quel identifiant, qu'il s'agisse d'une procédure, d'un type, d'un composant etc. Gardez une chose a l'esprit, c'est que l'identifiant doit permettre l'identification du type et/ou de l'utilité de l'élément qu'il nome.
Il ne doit n'y être trop court, ni trop long et ne doit en aucun cas avoir le même nom qu'un autre élément accessible dans l'unité en cours ou une autre.
Vous constaterez par vous même la jolie erreur des développeurs de Borland qui ont laissé le nom RECT a un argument dans l'événement OnDrawItem du composant TListBox... Ce nom d'argument écrase directement la fonction RECT() de l'unité Classes ce qui empêche l'utilisation de cette dernière dans cet événement et pourtant tout le monde sait a quel point cette fonction est utilisée pour les dessins dans les canvas.
Ce genre d'erreur force le développeur a "forcer" le nom de l'unité qui contient la fonction et donc il doit ajouter Classes.Rect() pour éviter les confusions du compilateur.
Au-delà de ces conventions d'écriture, vous pouvez (et devriez systématiquement) ajouter des commentaires court et explicite au dessus ou à coté des déclarations pour expliquer plus en détails le rôle d'un élément de code, l'intervalle min..max d'une valeur, les restrictions, etc.
F.1) Les types en général :
L'écriture d'un nom de type commenceras toujours par la lettre majuscule "T" (pour type).
Cette convention s'applique sur tout les types a l'exception du type Interface qui lui commenceras par la lettre majuscule "I" (pour interface).
Pour un type Interface, on commencera non seulement par la lettre "I" mais on ajoutera également à la fin la dénomination "Interface".
Pour un type pointeur, on ajoutera la lettre minuscule ou majuscule "p" ou "P" (pour pointeur).
Exemple :
TColor = $F7FFFFFF..$FFFFFFFF;
TComboBox = class;
IOLEInterface = interface;
IHTTPInterface = interface;
pColor = ^TColor;
pPoint = ^TPoint;
F.2) Les types énumérés, ensembles et tableaux :
L'ajout de certaines dénominations dans le nom du type ou de la variable peut être utile pour la différencier d'un type dérivé ou quasi identique, par exemple pour les types "Set of" la plupart du temps on mettra au pluriels le type Set of [type]. Pour les types tableaux "array of" on ajouteras la lettre majuscule "A" après le "T" majuscule ou aussi le préfixe "Arr" ou encore le suffixe "Array" après le nom du type.
Pour les types tableaux, l'ajout de dénominateur tel "vector", "matrix", "tri", "quad" permettent de définir encore plus le type.
La dénomination "Dyn" (pour dynamique) permet de faire la différence entre un tableau statique (array[0..n] of) et un tableau dynamique (array of)
Pour les type énumérés, les identificateurs de valeurs commencerons généralement par deux lettres significative en minuscule, elles correspondent la plupart du temps aux "initiales" du nom du type.
Exemple :
TFontStyle = (fsBold, fsItalic, fsUnderstrike);
TFontStyles = set of TFontStyle;
TTextAlignment = (taLeft, taCenter, taRight);
TFontStylesDynArray = array of TFontStyles;
TIntegerDynQuadArray = array of array[0..3] of integer;
F.3) Les types méthodes :
Pour les types Procédure ou Fonction, on ajouteras non seulement la lettre majuscule "T" au début du nom, mais également le suffixe "Proc" ou "Func" a la fin du nom de l'identifiant, "Event" si il s'agit d'un événement, Message si il s'agit d'un message.
Exemple :
TNotifyEvent = procedure(Sender: TObject) of object;
TTimeEvent = procedure(Sender: TObject; ATime : TTime) of object;
TIntegerProc = procedure(Value: Integer);
TFloatProc = procedure(Value: Extended);
TIntegerFunc = function(Value: Integer): Integer;
TFloatFunc = function(Value: Extended): Extended;
F.4) Les variables :
Les variables n'ont pas réellement de conventions, sauf a l'identique des types ensembles ou tableaux, l'ajout de dénominateurs permettant d'identifier leurs type d'origine.
Les deux seules vraies conventions pour les variables s'applique seulement sur Les arguments de méthodes, ou le nom des identifiants devrait toujours commencer par la lettre "A".
Exemple :
function RectWidth(ARect: TRect): integer;
Et les variables déclarées en zone private dans une classe, qui doivent commencer par la lettre "F".
Exemple :
TTestClasse = class
private
fInt : Integer;
fFlt : Extended;
end;
F.5) Les constantes :
Les constantes sont régies par les mêmes conventions que les variables.
Vous pouvez, pour les différencier des variables, ajouter une lettre majuscule "C" devant le nom de l'identifiant ou encore, comme nous le rappel si bien Florenth (et d'ailleurs je vois et fais souvent cela aussi) écrire la constante avec une convention C++ soit en majuscule avec underscore entre chaque mots.
Exemple :
Const
CDegRad = 180/Pi;
DEG_RAD = 180/Pi;
F.6) Les méthodes, procédures et fonctions :
Les méthodes doivent elles aussi avoir un nom qui définit correctement leurs utilisation.
La plupart du temps un nom simple comme Draw, Paint, Refresh permet de tout de suite savoir a quoi elles servent.
Il existe néanmoins des conventions spéciales pour certaines méthodes :
- Les méthodes d'appels d'événements dans une classe commenceront généralement par "Do". (DoTextChange)
- Les méthodes événements commenceront en général par "On". (OnTextChange)
- Les messages commenceront en général par "CM" ou "WM". (CMTextChange)
- Les méthodes servant à définir une valeur commenceront par "Set" (SetText)
- Les méthodes servant à renvoyer une valeur commenceront par "Get" (GetText)
- Les méthodes servant à connaitre un état particulier commenceront par "Is" (IsTextEmpty)
- Les méthodes de conversions A vers B devront contenir le nom des deux type séparés par "To" (TextToUnicode)