Parameterontwerp
Notitie
Deze inhoud wordt opnieuw afgedrukt door toestemming van Pearson Education, Inc. van Framework Design Guidelines: Conventions, Idioms en Patterns for Reusable .NET Libraries, 2nd Edition. Die editie werd in 2008 gepubliceerd en het boek is sindsdien volledig herzien in de derde editie. Sommige informatie op deze pagina is mogelijk verouderd.
Deze sectie bevat algemene richtlijnen voor het ontwerpen van parameters, inclusief secties met richtlijnen voor het controleren van argumenten. Daarnaast moet u verwijzen naar de richtlijnen die worden beschreven in Naamgevingsparameters.
✔️ GEBRUIK het minst afgeleide parametertype dat de functionaliteit biedt die door het lid is vereist.
Stel dat u een methode wilt ontwerpen waarmee een verzameling wordt opgesomd en elk item in de console wordt afgedrukt. Een dergelijke methode moet bijvoorbeeld als parameter worden gebruikt IEnumerable , niet ArrayList of IListals voorbeeld.
❌ GEBRUIK GEEN gereserveerde parameters.
Als er in een toekomstige versie meer invoer voor een lid nodig is, kan er een nieuwe overbelasting worden toegevoegd.
❌ U hebt geen openbaar toegankelijke methoden die aanwijzers, matrices van aanwijzers of multidimensionale matrices als parameters gebruiken.
Aanwijzers en multidimensionale matrices zijn relatief moeilijk te gebruiken. In bijna alle gevallen kunnen API's opnieuw worden ontworpen om te voorkomen dat deze typen als parameters worden gebruikt.
✔️ PLAATS alle out parameters na alle by-value en ref parameters (met uitzondering van parametermatrices), zelfs als dit resulteert in een inconsistentie in parametervolgorde tussen overbelastingen (zie Overbelasting van leden).
De out parameters kunnen worden gezien als extra retourwaarden en door ze samen te groeperen, is de methodehandtekening gemakkelijker te begrijpen.
✔️ DOE consistent in naamgevingsparameters bij het overschrijven van leden of het implementeren van interfaceleden.
Dit communiceert de relatie tussen de methoden beter.
Kiezen tussen Enum- en Booleaanse parameters
✔️ GEBRUIK enums als een lid anders twee of meer Booleaanse parameters zou hebben.
❌ GEBRUIK GEEN Booleaanse waarden, tenzij u er absoluut zeker van bent dat er nooit meer dan twee waarden nodig zijn.
Opsommingen geven u wat ruimte voor toekomstige toevoeging van waarden, maar u moet rekening houden met alle implicaties van het toevoegen van waarden aan enums, die worden beschreven in Enum Design.
✔️ OVERWEEG Booleaanse waarden te gebruiken voor constructorparameters die echt twee statuswaarden zijn en worden gewoon gebruikt om Booleaanse eigenschappen te initialiseren.
Argumenten valideren
✔️ DO valideert argumenten die zijn doorgegeven aan openbare, beveiligde of expliciet geïmplementeerde leden. Gooi System.ArgumentException, of een van de subklassen, als de validatie mislukt.
Houd er rekening mee dat de daadwerkelijke validatie niet noodzakelijkerwijs hoeft te gebeuren in het openbare of beveiligde lid zelf. Het kan gebeuren op een lager niveau in een privé- of interne routine. Het belangrijkste punt is dat het gehele oppervlak dat aan de eindgebruikers wordt blootgesteld, de argumenten controleert.
✔️ ArgumentNullException Als er een null-argument wordt doorgegeven en het lid geen null-argumenten ondersteunt.
✔️ DO valideert enumparameters.
Neem niet aan dat opsommingsargumenten binnen het bereik liggen dat is gedefinieerd door de enum. Met de CLR kan elke gehele waarde worden gecast naar een enumwaarde, zelfs als de waarde niet is gedefinieerd in de enum.
❌ NIET gebruiken Enum.IsDefined voor opsommingsbereikcontroles.
✔️ Houd er rekening mee dat veranderlijke argumenten mogelijk zijn gewijzigd nadat ze zijn gevalideerd.
Als het lid beveiligingsgevoelig is, wordt u aangeraden een kopie te maken en vervolgens het argument te valideren en te verwerken.
Parameter doorgeven
Vanuit het perspectief van een frameworkontwerper zijn er drie hoofdgroepen parameters: parameters met waarde, ref parameters en out parameters.
Wanneer een argument wordt doorgegeven via een by-value-parameter, ontvangt het lid een kopie van het werkelijke argument dat is doorgegeven. Als het argument een waardetype is, wordt er een kopie van het argument op de stapel geplaatst. Als het argument een verwijzingstype is, wordt er een kopie van de verwijzing op de stapel geplaatst. De populairste CLR-talen, zoals C#, VB.NET en C++, geven standaard parameters door op waarde.
Wanneer een argument wordt doorgegeven via een ref parameter, ontvangt het lid een verwijzing naar het werkelijke argument dat is doorgegeven. Als het argument een waardetype is, wordt een verwijzing naar het argument op de stapel geplaatst. Als het argument een verwijzingstype is, wordt een verwijzing naar de verwijzing op de stack geplaatst. Ref parameters kunnen worden gebruikt om het lid toe te staan argumenten te wijzigen die door de aanroeper zijn doorgegeven.
Out parameters zijn vergelijkbaar met ref parameters, met enkele kleine verschillen. De parameter wordt in eerste instantie beschouwd als niet-toegewezen en kan niet worden gelezen in de hoofdtekst van het lid voordat aan de parameter een bepaalde waarde wordt toegewezen. Ook moet aan de parameter een bepaalde waarde worden toegewezen voordat het lid wordt geretourneerd.
❌ VERMIJD het gebruik out of ref de parameters.
Het gebruik out of ref de parameters vereist ervaring met aanwijzers, inzicht in hoe waardetypen en verwijzingstypen verschillen en methoden verwerken met meerdere retourwaarden. Ook wordt het verschil tussen out en ref parameters niet algemeen begrepen. Frameworkarchitecten die voor een algemeen publiek ontwerpen, mogen niet verwachten dat gebruikers bekwaam worden in het werken met out of ref parameters.
❌ Geef referentietypen NIET door op referentie.
Er zijn enkele beperkte uitzonderingen op de regel, zoals een methode die kan worden gebruikt om verwijzingen te wisselen.
Leden met variabel aantal parameters
Leden die een variabel aantal argumenten kunnen gebruiken, worden uitgedrukt door een matrixparameter op te geven. Biedt bijvoorbeeld String de volgende methode:
public class String {
public static string Format(string format, object[] parameters);
}
Een gebruiker kan de String.Format methode vervolgens als volgt aanroepen:
String.Format("File {0} not found in {1}",new object[]{filename,directory});
Als u het trefwoord C#-parameters toevoegt aan een matrixparameter, wordt de parameter gewijzigd in een zogenaamde parameterparameter params en krijgt u een snelkoppeling om een tijdelijke matrix te maken.
public class String {
public static string Format(string format, params object[] parameters);
}
Hierdoor kan de gebruiker de methode aanroepen door de matrixelementen rechtstreeks in de argumentenlijst door te geven.
String.Format("File {0} not found in {1}",filename,directory);
Houd er rekening mee dat het trefwoord params alleen kan worden toegevoegd aan de laatste parameter in de parameterlijst.
✔️ OVERWEEG het trefwoord parameters toe te voegen aan matrixparameters als u verwacht dat de eindgebruikers matrices doorgeven met een klein aantal elementen. Als wordt verwacht dat veel elementen in algemene scenario's worden doorgegeven, geven gebruikers deze elementen waarschijnlijk toch niet door en is het trefwoord params dus niet nodig.
❌ VERMIJD het gebruik van parametermatrices als de aanroeper bijna altijd de invoer al in een matrix zou hebben.
Leden met bytematrixparameters zouden bijvoorbeeld bijna nooit worden aangeroepen door afzonderlijke bytes door te geven. Daarom gebruiken bytematrixparameters in .NET Framework het trefwoord params niet.
❌ GEBRUIK GEEN parametermatrices als de matrix wordt gewijzigd door het lid dat de parameter parameter paramsmatrix gebruikt.
Vanwege het feit dat veel compilers de argumenten omzetten in het lid in een tijdelijke matrix op de aanroepsite, kan de matrix een tijdelijk object zijn en daarom gaan eventuele wijzigingen in de matrix verloren.
✔️ OVERWEEG het trefwoord params te gebruiken in een eenvoudige overbelasting, zelfs als een complexere overbelasting het niet kon gebruiken.
Stel uzelf de vraag of gebruikers de parametermatrix in één overbelasting zouden hebben, zelfs als deze zich niet in alle overbelastingen bevindt.
✔️ PROBEER PARAMETERS te orden om het trefwoord params te gebruiken.
✔️ OVERWEEG speciale overbelastingen en codepaden te bieden voor aanroepen met een klein aantal argumenten in uiterst prestatiegevoelige API's.
Dit maakt het mogelijk om te voorkomen dat er matrixobjecten worden gemaakt wanneer de API wordt aangeroepen met een klein aantal argumenten. Vorm de namen van de parameters door een enkelvoudige vorm van de matrixparameter te gebruiken en een numeriek achtervoegsel toe te voegen.
U moet dit alleen doen als u het volledige codepad gaat gebruiken, niet alleen een matrix maakt en de meer algemene methode aanroept.
✔️ Houd er rekening mee dat null kan worden doorgegeven als een parametermatrixargument.
Controleer of de matrix niet null is voordat deze wordt verwerkt.
❌ GEBRUIK NIET de varargs methoden, ook wel bekend als het beletselteken.
Sommige CLR-talen, zoals C++, ondersteunen een alternatieve conventie voor het doorgeven van variabeleparameterlijsten die methoden worden genoemd varargs . De conventie mag niet worden gebruikt in frameworks, omdat het niet cls-compatibel is.
Aanwijzerparameters
In het algemeen mogen aanwijzers niet worden weergegeven in het openbare oppervlak van een goed ontworpen beheerd codeframework. Meestal moeten aanwijzers worden ingekapseld. In sommige gevallen zijn aanwijzers echter vereist om interoperabiliteitsredenen en is het gebruik van pointers in dergelijke gevallen passend.
✔️ Geef een alternatief op voor elk lid dat een aanwijzerargument gebruikt, omdat aanwijzers niet cls-compatibel zijn.
❌ VERMIJD het uitvoeren van dure argumentcontrole van aanwijzerargumenten.
✔️ DO volg algemene conventies met betrekking tot aanwijzers bij het ontwerpen van leden met aanwijzers.
Het is bijvoorbeeld niet nodig om de beginindex door te geven, omdat eenvoudige rekenkundige aanwijzers kunnen worden gebruikt om hetzelfde resultaat te bereiken.
© Delen 2005, 2009 Microsoft Corporation. Alle rechten voorbehouden.
Herdrukt door toestemming van Pearson Education, Inc. van Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition by Krzysztof Cwalina and Brad Abrams, published oct 22, 2008 by Addison-Wesley Professional als onderdeel van de Microsoft Windows Development Series.