Parameter Design 

The guidelines in this topic help you select the correct types and names for member parameters. The following topics also present design guidelines for parameters.

• Choosing Between Enumerations and Boolean Parameters

• Members with a Variable Number of Parameters

• Pointer Parameters

• Passing Parameters

• Validating Arguments

Do use the least-derived parameter type that provides the functionality required by the member.

The following code example illustrates this guideline. The BookInfo class inherits from the Publication class. The Manager class implements two methods: BadGetAuthorBiography and GoodGetAuthorBiography. BadGetAuthorBiography uses references to BookInfo objects even though it uses only members declared in Publication. The GoodGetAuthorBiography method demonstrates the correct design.

' A Class with some basic information.
Public Class Publication
    Dim Protected authorValue as String
    Dim Protected publicationDateValue as DateTime
    
    Public Sub new(author as String, publishDate as DateTime)
        Me.authorValue = author
        Me.PublicationDateValue = publishDate
    End Sub
    
    Public Readonly Property  PublicationDate as DateTime 
        Get
            Return publicationDateValue
        End Get
    End Property
    
    Public Readonly Property Author as String
        Get 
            Return authorValue
        End Get
    End Property
End Class

' A Class that derives from Publication
Public Class BookInfo 
    Inherits Publication

    Dim isbnValue as String
    
    Public Sub new(author as string, _
        publishDate as DateTime, _
        isbn as String) 
        MyBase.New(author, publishDate)
        Me.isbnValue = isbn
    End Sub
    
    Public Readonly Property Isbn as String
        Get 
            Return isbnValue
        End Get
    End Property
End Class

Public Class Manager
    ' This method does not use the Isbn member
    ' so it doesn't need a specialized reference to Books
    Shared Function BadGetAuthorBiography(book as BookInfo) as String
        Dim biography as String = ""
        Dim author as String = book.Author
        ' Do work here.
        Return biography
    End Function
    
    ' This method shows the correct design.
    Shared Function GoodGetAuthorBiography(item as Publication) as String
        Dim biography as String = ""
        Dim author as String = item.Author
        ' Do work here.
        Return biography
    End Function

// A class with some basic information.
public class Publication
{
    string author;
    DateTime publicationDate;
    
    public Publication(string author, DateTime publishDate)
    {
        this.author = author;
        this.publicationDate = publishDate;
    }
    public DateTime PublicationDate
    {
        get {return publicationDate;}
    }
    public string Author
    {
        get {return author;}
    }
}

// A class that derives from Publication
public class BookInfo :Publication
{
    string isbn;
    public BookInfo(string author, DateTime publishDate, string isbn) :
            base(author, publishDate)
    {
        this.isbn = isbn;
    }
    public string Isbn
    {
        get {return isbn;}
    }
}

public class Manager
{
    // This method does not use the Isbn member
    // so it doesn't need a specialized reference to Books
    static string BadGetAuthorBiography(BookInfo book)
    {
        string biography = "";
        string author = book.Author;
        // Do work here.
        return biography;

    }
    // This method shows the correct design.
    static string GoodGetAuthorBiography(Publication item)
    {
        string biography = "";
        string author = item.Author;
        // Do work here.
        return biography;
    }

Do not use reserved parameters.

Future versions of a library can add new overloads that take additional parameters.

The following code example first demonstrates an incorrect method that violates this guideline, and then shows methods with the correct design.

    Public Sub BadStoreTimeDifference (localDate as DateTime, _
        toWhere as TimeZone, _
        reserved as Object)
        ' Do work here.
    End Sub

Public Sub GoodCStoreTimeDifference (localDate as DateTime, _
    toWhere as TimeZone)
    ' Do work here.
End Sub

Public Sub GoodCStoreTimeDifference (localDate as DateTime, _
    toWhere as TimeZone, _
    useDayLightSavingsTime as Boolean)
    ' Do work here.
End Sub

    public void BadStoreTimeDifference (DateTime localDate, 
        TimeZone toWhere, 
        Object reserved)
    {
        // Do work here.
    }

public void GoodCStoreTimeDifference (DateTime localDate, 
    TimeZone toWhere)
{
    // Do work here.
}
public void GoodCStoreTimeDifference (DateTime localDate, 
    TimeZone toWhere, 
    bool useDayLightSavingsTime)
{
    // Do work here.
}

Do not use publicly exposed methods that take pointers, arrays of pointers, or multidimensional arrays as parameters.

Knowledge of these advanced features should not be required to use most libraries.

Do place all out parameters after all of the pass-by-value and ref parameters (excluding parameter arrays), even if this results in an inconsistency in parameter ordering between overloads.

This convention makes the method signature easier to understand.

Do be consistent in naming parameters when overriding members or implementing interface members.

Overrides should use the same parameter names. Overloads should use the same parameter names as the declaring member. Interface implementations should use the same names defined in the interface member signature.

Portions Copyright 2005 Microsoft Corporation. All rights reserved.

Portions Copyright Addison-Wesley Corporation. All rights reserved.

For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.

See Also

Other Resources

Member Design Guidelines
Design Guidelines for Developing Class Libraries