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.