Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

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.

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
{
    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 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.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.