This documentation is archived and is not being maintained.

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


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


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.

Show: