Question Contenu de Source en général ...

Et de source interprété en particulier (Script/Sql/etc.).

Chapitre premier : L’entête.

L’entête en général est un gros pavé de commentaires qui se doit de contenir :

Le nom du script (même si sa semble idiot).
Les autres scripts auxquels celui-ci serait lié de façon obligatoire (par exemple ceux contenant des fonctions utilisées dans celui-ci). En oubliant pas de mettre une brève description de ces scripts liés (Surtout les appelés, n’ajouter les appelants que si c’est vraiment important).
Une description plus ou moins détaillée de la fonctionnalité du script en cours. Avec pas forcément des détails techniques, sauf si ceux-ci ont une importance particulière.
Une description détaillée de chacun des paramètres s’il y en a. Leur signification et leur usage et leur format précis et leur valeur par défaut.
Et pour finir, un historique des modifications avec dates, intervenant et description de la modification.

ATTENTION : Toute la partie se trouvant au dessus de l’historique des modifications doit refléter la réalité actuelle du script. L’historique des modifications n’étant là que pour mémoire et chronologie. Par exemple, si vous ajoutez un paramètre à votre script, celui-ci doit être présent de façon indistinct des autres dans la section qui les décrits, l’historique n’étant là que pour mémoire de la date d’ajout de ce paramètre.

Voici un bref exemple de ce que pourrait être un entête de script.
[code:1]
# Script_Presentation_1A.ps1

#

---

# -- Scripts liés
#

---

# --
# ./Indentation_1A.ps1 Script de présentation de l'indentation des sources
# ./Nommage_1A.ps1 Script de présentation de nommage des objets des sources
# --
#

---

# -- Description
#

---

# --
# -- Ce sript est censé servir d'exemple pour la formalisation de l'écriture d'un
# -- code source. Il ne décrit pas une vérité, mais plutot nu état d'esprit qui
# -- permet de faire des sources. Lisibles et réutilisables par le plus grand nombre
# --
#

---

# -- Parametres
#

---

# --
# -- P_User [string] = 'Anonyme' Code Uitlisateur Windows du lanceur du script
# -- (Maxi 30 Caractères)
# -- P_Doma [string] = '' Domaine de la session de l'utilisateur courant
# -- (Declenche Throw si vide)
# --
#

---

# -- Historique
#

---

# -- 10/10/2007 USERX Ajout de la laison avec le script Nommage_1A.ps1
# -- 20/12/2007 USERY Moficiation du parametre P_Doma pour demander
# -- le domaine si non renseigner au lancement.
# --
#

---

[/code:1]Vous remarquerez que j’ai ici intégré la version (1A) au nom du script. C’est une des façons de faire, il en existe bien d’autres. Mais je reviendrais plus tard sur ce qui concerne le nommage des choses.

PS : Encore une fois je n’édicte pas une loi, très loin de moi cette idée, je ne fait que proposer UNE solution.

Gardez bien en tête que un script, comme tout autre source, doit avoir une fonction bien précise dans un cadre bien précis, et une évolution/histoire/vécu bien réel.

A suivre ...

merci spirit ta formule me convient
je l'adopte

La première chose que l’on doit retrouver après un entête de source, c’est le catalogue des « Choses » que l’on va être amené à utiliser dans notre source. Ces « Choses » seront en général de trois types. Des Variables, des objets et des fonctions.

Certains langages permettent une déclaration « Localisée », c'est-à-dire que la déclaration de la variable se fait à l’endroit dans le code où on en a besoin. Si dans un langage comme VB.NET cela se justifie plus ou moins (J’explique après), il n’existe pas à ma connaissance de langage de script pour lequel se soit indiqué. Pour information, la particularité de VB.NET c’est de considérer qu’une variable déclarée dans un bloc IF par exemple, n’a pour portée QUE le bloc IF en question. Mais à ma connaissance en programmation c’est assez nouveau.

Ces déclarations en début de source sont importantes car elles permettent :
De faire un inventaire exhaustif des variables (avant même d’entrer dans le code).
De localiser à un seul endroit la liste et la description de toutes les variables du script.

Ainsi si je cherche en lisant le script une information sur une variable utilisée dans le source je sait exactement où la trouver de suite. C’est aussi valable pour les objets et les fonctions.

Ce catalogue doit être découpé (c’est un grand mot) en familles. Les familles de plus haut niveaux étant Variables/Objets/Fonctions. Au sein de chaque groupe, on peu décomposé en fonction des besoins. Il n’y a pas vraiment de règle encore une fois, plutôt du bon sens au cas par cas.

Il y a une autre chose qui est TRES importante dans ce chapitre, c’est le nommage de ces variables/objets/fonctions. Il est d’autant plus important, que le nom lui-même peut déjà donner au lecteur des informations primordiales. Encore une fois pas de règles. Il faut adapter à son besoin. Pour le moins, le nom d’une variable peut indiquer deux choses : Sa portée et son type. Ensuite le nom contiendra une partie explicite d’un point de vue traitement.

Ainsi votre lecteur, après avoir été globalement informé de ce que fait votre script, saura à l’avance l’usage des variables utilisées dans celui-ci.

Voici donc un exemple de ce que pourrait être notre partie déclarative.
[code:1]
# --
# -- Déclaration des Variables
# --

# -- Constantes
[string]$CStr_Compte = 'Login' # Compte a utiliser pour la connexion
[string]$CStr_Domaine = 'Domaine' # Nom du domaine par defaut
# --
[int]$CInt_MaxWait = 500 # Millisecondes maximum d'attente

# -- Globales (Script entier)
[datetime]$GDat_Jour = Get-Date # Date du jour du traitement
$Gdat_First = [datetime] # Premier jour du mois (Mode SANS instanciation)
# --
[boolean]$GBol_Flag = $true # Flag de Traitement ...

# --
# -- Déclaration des Objets
# --

# -- .NET
$GNet_Connexion = New-Object System.Data.Odbc.OdbcConnection # Connexion à la SGBD
$GNet_Command = $GNet_Connexion.CreateCommand() # Commande (SQL)

# -- WMI
$GWmi_Bios = get-wmiobject win32_bios # Infos sur le Bios machine

# --
# -- Déclaration des Fonctions
# --

Function MaFonction (..........)
{
# -- Déclarations
$VarInterne = [string] # Ici les déclarations sont locales
...
$VarInterne = $Cstr_Compte.SubString(1,5)
...
}

. /MonScriptContenantDesFonctions.ps1 # On éxécute en \". \" un script qui
# déclare des fonctions stockées
# dans un autre source mutualisé
[/code:1]


Bien sur, il est à noter que la notion de variables n’existe pas vraiment dans PS, puisque se sont en réalité des objets de .NET. Quand on écrit [string], c’est exactement pareil que si l’on écrivait [System.IO.Directory]. On fait toujours référence à la classe d’objet. La séparation dans le source des variables et des objets est donc de plus en plus symbolique.<br><br>Message édité par: Spirit, à: 20/02/08 15:42

Arnaud écrit:

Excellente initiative Spirit ! Il faudrait faire de même pour les bonnes pratiques en PowerShell...

Heuuu il m'avais semblé que mes exemples de code étaient en PowerShell ... Meme si je me suis voulu plus généraliste. Mon but ici etant de démontrer que ce que je dis est applicable en powershell, sinon je ne l'aurait pas poster ici.

Juste une remarque au passage:

Certains langages permettent une déclaration « Localisée », ... c’est de considérer qu’une variable déclarée dans un bloc IF par exemple, n’a pour portée QUE le bloc IF en question. Mais à ma connaissance en programmation c’est assez nouveau.

Cette notion existe aussi en PowerShell. C'est la notion de portée (ou scope en anglais).

La \&quot;Portée\&quot; des variables existe dans tous les langages de programmation que je connais. Ce que je voulais indiquer plus particulièrement c'est que en VB.NET (à ma connaissance) le code suivant n'aurait pas fonctionné, car la variable b du bloc IF n'est pas connue en dehors de ce bloc IF ENDIF.
[code:1][string]$a = 'Un'
If ( $a = 'Un' )
{
[string]$b = 'Deux'
}
$a
$b[/code:1]

Ah oui, une dernière chose :

Quand on écrit [string], c’est exactement pareil que si l’on écrivait [System.IO.Directory].

Je ne suis pas tout à fait d'accord, mais c'est un détail car ton idée est juste en disant que \&quot;tout est objet\&quot;.

Là était bien mon idée en effet. Et je suis d'accord que j'aurait dû choisir une classe instanciable au lieu de System.IO.Directory qui elle ne l'est pas en effet ^^.

Bon désolé pour toutes ces petites imperfections.