Surcharge de membre

Article
08/10/2011

La signature d'un membre comprend son nom et sa liste de paramètres. Chaque signature de membre doit être unique dans le type. Les membres peuvent avoir le même nom pour autant que leurs listes de paramètres diffèrent. Lorsque deux ou plusieurs membres d'un type représentent le même type de membre (méthode, propriété, constructeur, etc.), qu'ils possèdent le même nom mais des listes de paramètres différentes, le membre est dit surchargé. Par exemple, la classe Array contient deux méthodes CopyTo. La première méthode prend un tableau et une valeur Int32 tandis que la deuxième méthode prend un tableau et une valeur Int64.

Remarque
La modification du type de retour d'une méthode ne rend pas la méthode unique comme le déclare la spécification du Common Language Runtime.Vous ne pouvez pas définir de surcharges qui se distinguent uniquement par le type de retour.

Les membres surchargés doivent fournir des variations des mêmes fonctionnalités. Par exemple, il n'est pas correct pour un type d'avoir deux membres CopyTo, le premier membre copiant des données vers un tableau et le second vers un fichier. La surcharge d'un membre sert généralement à fournir des surcharges qui prennent peu de paramètres, voire aucun, et sont simples à utiliser. Ces membres appellent des surcharges qui sont certes plus puissantes mais qui exigent aussi une plus grande expérience car elles sont plus difficiles à utiliser. Les surcharges simples prennent en charge des scénarios classiques qui consistent à passer des valeurs par défaut aux surcharges complexes. Par exemple, la classe File fournit des surcharges pour la méthode Open. La surcharge simple Open prend un chemin d'accès et un mode de fichier. Elle appelle la surcharge Open qui prend des paramètres de chemin d'accès, de mode de fichier, d'accès au fichier et de partage de fichiers, et fournit les valeurs par défaut fréquemment utilisées pour les paramètres d'accès au fichier et de partage de fichiers. Les développeurs qui n'ont pas besoin de la souplesse offerte par la surcharge complexe ne doivent pas nécessairement être familiarisés avec les modèles d'accès au fichier et de partage de fichiers pour ouvrir un fichier.

Pour simplifier la maintenance et le versioning, les surcharges plus simples doivent utiliser les surcharges complexes pour effectuer leurs actions ; les fonctionnalités sous-jacentes ne doivent pas être implémentées dans plusieurs emplacements.

Indications concernant la surcharge

Les règles suivantes permettent de garantir la conception correcte de vos membres surchargés.

Essayez d'utiliser des noms de paramètres descriptifs pour indiquer la valeur par défaut utilisée par les surcharges plus simples.

Cette règle s'applique plus spécialement aux paramètres Boolean. Le nom de paramètre de la surcharge plus complexe doit indiquer la valeur par défaut fournie par la surcharge plus simple en décrivant l'action ou l'état opposé. Par exemple, la classe String fournit les surcharges suivantes :

Overloads Public Shared Function Compare( _
   ByVal strA As String, _
   ByVal strB As String _
) As Integer

Overloads Public Shared Function Compare( _
   ByVal strA As String, _
   ByVal strB As String, _
   ByVal ignoreCase As Boolean _
) As Integer

public static int Compare(
   string strA,
   string strB
);

public static int Compare(
   string strA,
   string strB,
   bool ignoreCase
);

La deuxième surcharge fournit un paramètre Boolean nommé ignoreCase. Cela indique que la surcharge plus simple respecte la casse et que vous devez utiliser la surcharge plus complexe uniquement lorsque vous souhaitez ignorer la casse. En général, la valeur par défaut doit être false.

Évitez les noms de paramètres variant de façon arbitraire d'une surcharge à l'autre. Si le paramètre d'une surcharge représente la même entrée qu'un paramètre d'une autre surcharge, les paramètres doivent avoir le même nom.

Par exemple, évitez la définition suivante :

Public Sub Write(message as String, stream as FileStream)
End Sub
Public Sub Write(line as String, file as FileStream, closeStream as Boolean)
End Sub

public void Write(string message, FileStream stream){}
public void Write(string line, FileStream file, bool closeStream){}

public:
    void Write(String^ message, FileStream^ stream){}
    void Write(String^ line, FileStream^ file, bool closeStream){}

La définition correcte de ces surcharges est la suivante :

Public Sub Write(message as String, stream as FileStream)
End Sub
Public Sub Write(message as String, stream as FileStream, _
    closeStream as Boolean)
End Sub

public void Write(string message, FileStream stream){}
public void Write(string message, FileStream stream, bool closeStream){}

public:
    void Write(String^ message, FileStream^ stream){}
    void Write(String^ message, FileStream^ stream, bool closeStream){}

Soyez cohérent dans le classement des paramètres des membres surchargés. Les paramètres de même nom doivent figurer à la même position dans toutes les surcharges.

Par exemple, évitez la définition suivante :

Public Sub Write( message as String, stream as FileStream)
End Sub
Public Sub Write(stream as FileStream, message as String, _
    closeStream as Boolean)
End Sub

public void Write(string message, FileStream stream){}
public void Write(FileStream stream,  string message, bool closeStream){}

public:
    void Write(String^ message, FileStream^ stream){}
    void Write(FileStream^ stream, String^ message, bool closeStream){}

La définition correcte de ces surcharges est la suivante :

Public Sub Write(message as String, stream as FileStream)
End Sub
Public Sub Write(message as String, stream as FileStream, _
    closeStream as Boolean)
End Sub

public void Write(string message, FileStream stream){}
public void Write(string message, FileStream stream, bool closeStream){}

public:
    void Write(String^ message, FileStream^ stream){}
    void Write(String^ message, FileStream^ stream, bool closeStream){}

Cette règle comporte deux contraintes :

Si une surcharge prend une liste d'arguments variable, la liste doit constituer le dernier paramètre.
Si la surcharge prend des paramètres out, par convention, ceux-ci doivent apparaître en dernière position.

Seule la plus longue surcharge doit être virtuelle (Overridable en Visual Basic) si l'extensibilité est nécessaire. Les surcharges plus courtes doivent appeler simplement une surcharge plus longue.

L'exemple de code suivant illustre cette pratique.

Public Sub Write(message as String, stream as FileStream)
    Me.Write(message, stream, false)
End Sub

Public Overridable Sub Write( _
    message as String, stream as FileStream, closeStream as Boolean)
    ' Do work here.
End Sub

public void Write(string message, FileStream stream)
{
    this.Write(message, stream, false);
}
public virtual void Write(string message, FileStream stream, bool closeStream)
{
    // Do work here.
}

public:
    void Write(String^ message, FileStream^ stream)
    {
        this->Write(message, stream, false);
    }

    virtual void Write(String^ message, FileStream^ stream, bool closeStream)
    {
        // Do work here.
    }

N'utilisez pas de modificateurs ref ou out pour surcharger des membres.

Par exemple, évitez le design suivant :

Public Sub Write(message as String,  count as Integer)


...


Public Sub Write(message as String, ByRef count as Integer)

public void Write(string message, int count)


...


public void Write(string message, out int count)

public:
    void Write(String^ message, int count)


...


void Write(String^ message, int% count)

En général, si cela se produit dans l'un de vos designs, cela indique probablement un problème de conception plus profond. Envisagez de renommer l'un des membres pour fournir des informations plus complètes sur l'action exacte effectuée par la méthode.

Autorisez des valeurs null (Nothing en Visual Basic) dans les arguments facultatifs. Si une méthode prend des arguments facultatifs qui sont des types référence, autorisez les valeurs null afin d'indiquer que la valeur par défaut doit être utilisée. De cette façon, vous évitez de devoir vérifier la présence de valeurs null avant d'appeler un membre.

Les développeurs ne devraient pas, par exemple, avoir à vérifier la présence de null dans l'exemple suivant.

Public Sub CopyFile (source as FileInfo, _
    destination as DirectoryInfo, _
    newName as string)

    If newName Is Nothing
        InternalCopyFile(source, destination) 
    Else
        InternalCopyFile(source, destination, newName)
    End If
End Sub

public void CopyFile (FileInfo source, DirectoryInfo destination, string newName)
{
    if (newName == null)
    {
        InternalCopyFile(source, destination);
    }
    else
    {
        InternalCopyFile(source, destination, newName);
    }
}

public:
    void CopyFile(FileInfo^ source, DirectoryInfo^ destination, String^ newName)
    {
        if (newName == nullptr)
       {
            InternalCopyFile(source, destination);
        }
        else
        {
            InternalCopyFile(source, destination, newName);
        }
    }

Utilisez la surcharge de membres au lieu de définir des membres avec des arguments par défaut. Les arguments par défaut ne sont pas conformes CLS et ne peuvent pas être utilisés à partir de certains langages.

L'exemple de code suivant illustre un design de méthode incorrect.

Public Sub Rotate (data as Matrix, Optional degrees as Integer = 180)
' Do rotation here
End Sub

Vous devez reconcevoir ce code sous la forme de deux surcharges, la surcharge plus simple fournissant la valeur par défaut. L'exemple de code suivant illustre le design correct.

Overloads Public Sub Rotate (data as Matrix)
    Rotate(data, 180)
End Sub

Overloads Public Sub Rotate (data as Matrix, degrees as Integer)
' Do rotation here
End Sub

Pour plus d'informations sur les règles de conception, consultez « règles de conception d'infrastructure : Conventions idiomes et modèles carnet de bibliothèques réutilisables framework » Krzysztof Cwalina et Brad Abrams, publiés par Addison-Wesley, 2005.

Voir aussi

Autres ressources

Instructions de conception des membres

Instructions de conception pour le développement de bibliothèques de classes

Partager via

Surcharge de membre

Indications concernant la surcharge

Voir aussi

Autres ressources

Ressources supplémentaires