Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Remarque
Ce contenu est réimprimé avec l’autorisation de Pearson Education, Inc. tiré de Lignes directrices de conception de framework : Conventions, Idiomes et Modèles pour les bibliothèques .NET réutilisables, 2ème édition. Cette édition a été publiée en 2008, et le livre a été entièrement révisé dans la troisième édition. Certaines informations de cette page peuvent être obsolètes.
Cette section fournit des instructions générales sur la conception des paramètres, y compris les sections avec des instructions pour la vérification des arguments. En outre, vous devriez vous référer aux directives décrites dans Paramètres de nommage.
✔️ Utilisez le type de paramètre le moins dérivé qui fournit les fonctionnalités requises par le membre.
Par exemple, supposons que vous souhaitiez concevoir une méthode qui énumère une collection et imprime chaque élément dans la console. Une telle méthode doit prendre IEnumerable comme paramètre, non ArrayList ou IList, par exemple.
❌ N’utilisez PAS les paramètres réservés.
Si davantage de paramètres pour un membre est nécessaire dans une version ultérieure, une nouvelle surcharge peut être ajoutée.
❌ N’avez PAS de méthodes exposées publiquement qui prennent des pointeurs, des tableaux de pointeurs ou des tableaux multidimensionnels en tant que paramètres.
Les pointeurs et les tableaux multidimensionnels sont relativement difficiles à utiliser correctement. Dans presque tous les cas, les API peuvent être repensées pour éviter de prendre ces types en tant que paramètres.
✔️ ASSUREZ-VOUS de placer tous les paramètres out après tous les paramètres par valeur et ref, à l'exception des tableaux de paramètres, même si cela entraîne une incohérence dans l'ordre des paramètres entre les surcharges (voir Surcharge de membre).
Les out paramètres peuvent être considérés comme des valeurs de retour supplémentaires et les regrouper, rend la signature de méthode plus facile à comprendre.
✔️ Soyez cohérent en nommant les paramètres lorsque vous substituez des membres ou implémentez des membres d'interface.
Cela permet de mieux communiquer la relation entre les méthodes.
Choix entre les paramètres enum et booléens
✔️ Utilisez des énumérations si un membre aurait autrement deux paramètres booléens ou plus.
❌ N’utilisez pas les booléens, sauf si vous êtes absolument sûr qu’il n’y aura jamais besoin de plus de deux valeurs.
Les énumérations vous donnent une place pour l’ajout futur de valeurs, mais vous devez être conscient de toutes les implications de l’ajout de valeurs à des énumérations, qui sont décrites dans Enum Design.
✔️ ENVISAGEZ d’utiliser des booléens pour les paramètres de constructeur qui sont réellement des valeurs à deux états et qui sont simplement utilisés pour initialiser des propriétés booléennes.
Validation des arguments
✔️ VALIDEZ les arguments passés aux membres publics, protégés ou explicitement implémentés. Lancez System.ArgumentException, ou l’une de ses sous-classes, si la validation échoue.
Notez que la validation réelle n’a pas nécessairement lieu dans le membre public ou protégé lui-même. Cela peut se produire à un niveau inférieur dans une routine privée ou interne. Le point principal est que l’ensemble de la surface exposée aux utilisateurs finaux vérifie les arguments.
✔️ LANCEZ ArgumentNullException si un argument Null est passé et que le membre ne prend pas en charge les arguments Null.
✔️ VALIDEZ les paramètres d’énumération.
Ne supposez pas que les arguments d’énumération se trouveront dans la plage définie par l’énumération. Le CLR autorise la conversion d’une valeur entière en une valeur enum même si la valeur n’est pas définie dans l’énumération.
❌ NE PAS utiliser Enum.IsDefined pour les vérifications de plage d’énumération.
✔️ N’oubliez pas que les arguments mutables peuvent avoir changé après leur validation.
Si le membre est sensible à la sécurité, il est recommandé de faire une copie, puis de valider et traiter l'argument.
Passage de paramètres
Du point de vue d’un concepteur d’infrastructure, il existe trois principaux groupes de paramètres : les paramètres par valeur, les paramètres de type ref, et les paramètres de type out.
Lorsqu’un argument est passé par le biais d’un paramètre par valeur, le membre reçoit une copie de l’argument réel passé. Si l’argument est un type valeur, une copie de l’argument est placée sur la pile. Si l’argument est un type référence, une copie de la référence est placée sur la pile. Les langages CLR les plus populaires, tels que C#, VB.NET et C++, passent par défaut les paramètres par valeur.
Lorsqu’un argument est passé par le biais d’un ref paramètre, le membre reçoit une référence à l’argument réel passé. Si l’argument est un type valeur, une référence à l’argument est placée sur la pile. Si l’argument est un type référence, une référence à la référence est placée sur la pile.
Ref les paramètres peuvent être utilisés pour permettre au membre de modifier les arguments passés par l’appelant.
Out les paramètres sont similaires aux ref paramètres, avec quelques petites différences. Le paramètre est initialement considéré comme non attribué et ne peut pas être lu dans le corps du membre avant qu'une valeur ne lui soit affectée. En outre, le paramètre doit être affecté à une valeur avant le retour du membre.
❌ ÉVITEZ d’utiliser out ou ref de paramètres.
L'utilisation des paramètres out ou ref nécessite une expérience avec des pointeurs, la compréhension de la façon dont les types de valeur et les types de référence diffèrent, et la gestion des méthodes avec plusieurs valeurs de retour. Par ailleurs, la différence entre les paramètres out et ref est généralement peu comprise. Les architectes de framework qui conçoivent pour un public général ne doivent pas s’attendre à ce que les utilisateurs soient compétents dans l’utilisation des paramètres out ou ref.
❌ NE PAS passer de types par référence par référence.
Il existe quelques exceptions limitées à la règle, telles qu’une méthode qui peut être utilisée pour échanger des références.
Membres avec le nombre variable de paramètres
Les membres qui peuvent prendre un nombre variable d’arguments sont exprimés en fournissant un paramètre de tableau. Par exemple, String fournit la méthode suivante :
public class String {
public static string Format(string format, object[] parameters);
}
Un utilisateur peut ensuite appeler la String.Format méthode, comme suit :
String.Format("File {0} not found in {1}",new object[]{filename,directory});
L’ajout du mot clé params C# à un paramètre de tableau modifie le paramètre en paramètre de tableau appelé params et fournit un raccourci pour créer un tableau temporaire.
public class String {
public static string Format(string format, params object[] parameters);
}
Cela permet à l’utilisateur d’appeler la méthode en passant les éléments de tableau directement dans la liste d’arguments.
String.Format("File {0} not found in {1}",filename,directory);
Notez que le mot clé params ne peut être ajouté qu’au dernier paramètre de la liste des paramètres.
✔️ ENVISAGEZ d’ajouter le mot clé params aux paramètres de tableau si vous attendez que les utilisateurs finaux passent des tableaux avec un petit nombre d’éléments. Si l’on s’attend à ce que beaucoup d’éléments soient transmis dans des scénarios courants, les utilisateurs ne transmettront probablement pas ces éléments inline de toute façon, et donc le mot clé params n’est pas nécessaire.
❌ Évitez d'utiliser des tableaux params si l'appelant aura presque toujours l'entrée déjà sous forme de tableau.
Par exemple, les membres avec des paramètres de tableau d’octets ne sont presque jamais appelés en passant des octets individuels. Pour cette raison, les paramètres de tableau d’octets du .NET Framework n’utilisent pas le mot clé params.
❌ N’utilisez PAS les tableaux params si le tableau est modifié par le membre prenant le paramètre de tableau params.
En raison du fait que de nombreux compilateurs transforment les arguments en tableau temporaire sur le site d’appel, le tableau peut être un objet temporaire, et par conséquent, toutes les modifications apportées au tableau seront perdues.
✔️ ENVISAGEZ d’utiliser le mot-clé params pour une surcharge simple, même si une surcharge plus complexe ne pouvait pas l'utiliser.
Demandez-vous si les utilisateurs trouveraient utile d’avoir le tableau params via une surcharge, même s'il n'était pas présent dans toutes les surcharges.
✔️ Essayez d’ordonner les paramètres pour permettre d’utiliser le mot clé params.
✔️ ENVISAGEZ de fournir des surcharges spéciales et des chemins de code pour les appels avec un petit nombre d’arguments dans des API extrêmement sensibles aux performances.
Cela permet d’éviter de créer des objets de tableau lorsque l’API est appelée avec un petit nombre d’arguments. Formez les noms des paramètres en prenant une forme singulière du paramètre de tableau et en ajoutant un suffixe numérique.
Vous ne devez le faire que si vous envisagez de traiter un cas particulier pour l’ensemble du chemin d'exécution du code, pas seulement créer un tableau et appeler une méthode plus générale.
✔️ N’oubliez pas que null peut être passé en tant qu’argument de tableau params.
Vous devez vérifier que le tableau n’est pas null avant le traitement.
❌ N’utilisez PAS les méthodes varargs, également appelées points de suspension.
Certains langages CLR, tels que C++, prennent en charge une autre convention pour passer des listes de paramètres variables appelées varargs méthodes. La convention ne doit pas être utilisée dans les frameworks, car elle n'est pas conforme CLS.
Paramètres du pointeur
En règle générale, les pointeurs ne doivent pas apparaître dans la surface publique d’une infrastructure de code managé bien conçue. La plupart du temps, les pointeurs doivent être encapsulés. Toutefois, dans certains cas, les pointeurs sont requis pour des raisons d’interopérabilité et l’utilisation de pointeurs dans de tels cas est appropriée.
✔️ Fournissez une alternative pour tout membre qui accepte un argument de pointeur, car les pointeurs ne sont pas conformes aux spécifications CLS.
❌ ÉVITEZ d’effectuer une vérification d’argument coûteuse des arguments de pointeur.
✔️ SUIVEZ les conventions courantes liées au pointeur lors de la conception de membres avec des pointeurs.
Par exemple, il n’est pas nécessaire de passer l’index de début, car un simple pointeur arithmétique peut être utilisé pour accomplir le même résultat.
Portions © 2005, 2009 Microsoft Corporation. Tous les droits réservés.
Réimprimé par l’autorisation de Pearson Education, Inc. tiré de Framework Design Guidelines : Conventions, Idioms et Patterns pour les bibliothèques .NET réutilisables, 2e édition par Krzysztof Cwalina et Brad Abrams, publié le 22 octobre 2008 par Addison-Wesley Professional dans le cadre de la Série de développement Microsoft Windows.