Projekt parametru

Ta sekcja zawiera szerokie wytyczne dotyczące projektowania parametrów, w tym sekcje z wytycznymi dotyczącymi sprawdzania argumentów. Ponadto należy odnieść się do wytycznych opisanych w Naming Parameters.

✔️ Używaj najmniej pochodnego typu parametru, który zapewnia funkcjonalność wymaganą przez członka.

Załóżmy na przykład, że chcesz zaprojektować metodę, która wylicza kolekcję i drukuje każdy element w konsoli. Taka metoda powinna przyjmować IEnumerable jako parametr, a nie ArrayList lub IList, na przykład.

❌ NIE UŻYWAJ parametrów zarezerwowanych.

Jeśli w przyszłych wersjach będzie potrzebne więcej danych wejściowych dla członka klasy, można dodać nowe przeciążenie.

❌ NIE POWINNY mieć publicznie dostępnych metod, które jako parametry przyjmują wskaźniki, tablice wskaźników lub tablice wielowymiarowe.

Wskaźniki i tablice wielowymiarowe są stosunkowo trudne do prawidłowego użycia. W prawie wszystkich przypadkach interfejsy API można przeprojektować, aby uniknąć podejmowania tych typów jako parametrów.

✔️ Umieść wszystkie out parametry po wszystkich parametrach przekazywanych przez wartość i ref parametrach (z wyłączeniem tablic parametrów), nawet jeśli powoduje to niespójność w kolejności parametrów między przeciążeniami (zobacz Przeciążanie członków).

out Parametry mogą być postrzegane jako dodatkowe wartości zwracane, a ich grupowanie sprawia, że sygnatura metody jest łatwiejsza do zrozumienia.

✔️ Należy zachować spójność w nazewnictwie parametrów podczas zastępowania składników lub implementowania składników interfejsu.

Dzięki temu lepiej komunikuje się relacja między metodami.

Wybór między parametrami typu Enum a parametrami typu boolean

✔️ Należy używać wyliczenia, jeśli członek inaczej miałby dwa lub więcej parametrów logicznych.

❌ NIE należy używać wartości logicznych, chyba że jesteś absolutnie pewny, że nigdy nie zajdzie potrzeba posiadania więcej niż dwóch wartości.

Enumeracje dają trochę miejsca na przyszłe wartości, ale należy pamiętać o wszystkich implikacjach dodawania wartości do enumeracji, które opisano w Projektowanie Enummów.

✔️ ROZWAŻ użycie wartości logicznych dla parametrów konstruktora, które są naprawdę wartościami dwustanowymi i są po prostu używane do inicjowania właściwości logicznych.

Weryfikowanie argumentów

✔️ Weryfikuj argumenty przekazywane do publicznych, chronionych lub jawnie zaimplementowanych członków. Wyrzuć System.ArgumentExceptionelement lub jedną z jego podklas, jeśli walidacja zakończy się niepowodzeniem.

Należy pamiętać, że rzeczywista walidacja nie musi odbywać się w samym publicznym lub chronionym elemencie członkowskim. Może się to zdarzyć na niższym poziomie w niektórej prywatnej lub wewnętrznej rutynie. Głównym punktem jest to, że cały obszar powierzchni uwidoczniony dla użytkowników końcowych sprawdza argumenty.

✔️ Należy wyrzucić ArgumentNullException, jeśli argument null jest przekazywany, a element członkowski nie obsługuje argumentów null.

✔️ Upewnij się, że parametry typu wyliczeniowego są poprawne.

Nie zakładaj, że argumenty wyliczenia będą znajdować się w zakresie zdefiniowanym przez wyliczenie. CLR umożliwia rzutowanie dowolnej wartości całkowitej na wartość wyliczeniową, nawet jeśli wartość nie jest zdefiniowana w wyliczeniu.

❌ NIE NALEŻY używać Enum.IsDefined do sprawdzania zakresu wyliczenia.

✔️ Należy pamiętać, że argumenty modyfikowalne mogły ulec zmianie po ich zweryfikowaniu.

Jeśli członek jest wrażliwy pod względem bezpieczeństwa, zaleca się utworzenie kopii, a następnie sprawdzenie i przetworzenie argumentu.

Przekazywanie parametrów

Z perspektywy projektanta platformy istnieją trzy główne grupy parametrów: parametry według wartości, ref parametry i out parametry.

Gdy argument jest przekazywany przez parametr by-value, element członkowski otrzymuje kopię rzeczywistego argumentu przekazanego. Jeśli argument jest typem wartości, kopia argumentu zostanie umieszczona na stosie. Jeśli argument jest typem odwołania, kopia odwołania jest umieszczana na stosie. Najpopularniejsze języki CLR, takie jak C#, VB.NET i C++, domyślnie przekazują parametry według wartości.

Gdy argument jest przekazywany przez ref parametr, element członkowski otrzymuje odwołanie do rzeczywistego argumentu przekazanego. Jeśli argument jest typem wartości, odwołanie do argumentu jest umieszczane na stosie. Jeśli argument jest typem referencyjnym, na stosie umieszczane jest odwołanie do tego argumentu. Ref Parametry mogą służyć do zezwalania członkowi na modyfikowanie argumentów przekazywanych przez obiekt wywołujący.

Out parametry są podobne do ref parametrów, choć z niewielkimi różnicami. Parametr jest początkowo uznawany za nieprzypisany i nie można go odczytać w treści elementu członkowskiego, zanim zostanie przypisana pewna wartość. Ponadto parametr musi być przypisany do pewnej wartości przed zwróceniem elementu członkowskiego.

❌ UNIKAJ używania parametrów out lub ref.

Używanie out parametrów lub ref wymaga doświadczenia ze wskaźnikami, zrozumienia różnic typów wartości i typów odwołań oraz obsługi metod z wieloma wartościami zwracanymi. Ponadto różnica między parametrami out i ref nie jest powszechnie rozumiana. Architekci struktury projektujący dla odbiorców ogólnych nie powinni oczekiwać, że użytkownicy będą biegłi w pracy z parametrami out lub ref .

❌ NIE przekazuj typów odwołań przez odwołanie.

Istnieją pewne ograniczone wyjątki reguły, takie jak metoda, która może służyć do zamiany odwołań.

Elementy członkowskie ze zmienną liczbą parametrów

Członkowie, którzy mogą przyjmować zmienną liczbę argumentów, są wyrażani za pomocą podania parametru tablicy. Na przykład String udostępnia następującą metodę:

public class String {
    public static string Format(string format, object[] parameters);
}

Następnie użytkownik może wywołać metodę String.Format w następujący sposób:

String.Format("File {0} not found in {1}",new object[]{filename,directory});

Dodanie słowa kluczowego params języka C# do parametru tablicy zmienia parametr na tak zwany parametr tablicy params i udostępnia skrót do tworzenia tablicy tymczasowej.

public class String {
    public static string Format(string format, params object[] parameters);
}

Dzięki temu użytkownik może wywołać metodę, przekazując elementy tablicy bezpośrednio na liście argumentów.

String.Format("File {0} not found in {1}",filename,directory);

Należy pamiętać, że słowo kluczowe params można dodać tylko do ostatniego parametru na liście parametrów.

✔️ ROZWAŻ dodanie słowa kluczowego params do parametrów tablicy, jeśli oczekujesz, że użytkownicy końcowi przekażą tablice z niewielką liczbą elementów. Jeśli oczekuje się, że wiele elementów zostanie przekazanych w typowych scenariuszach, użytkownicy prawdopodobnie nie przekażą tych elementów bezpośrednio, więc słowo kluczowe params nie jest konieczne.

❌ UNIKAJ używania tablic params, jeśli obiekt wywołujący prawie zawsze będzie miał dane wejściowe już w tablicy.

Na przykład członkowie klasy z parametrami tablicy bajtów prawie nigdy nie będą wywoływani poprzez przekazywanie poszczególnych bajtów. Z tego powodu parametry tablicy bajtów w programie .NET Framework nie używają słowa kluczowego params.

❌ NIE należy używać tablicy params, jeśli jest ona modyfikowana przez członka zmieniającego parametr tablicy params.

Ze względu na fakt, że wiele kompilatorów zamienia argumenty funkcji członkowskiej na tymczasową tablicę w miejscu wywołania, tablica może być obiektem tymczasowym, dlatego wszelkie modyfikacje tablicy zostaną utracone.

✔️ ROZWAŻ użycie słowa kluczowego params w przeciążeniu prostym, nawet jeśli bardziej złożone przeciążenie nie może go używać.

Zadaj sobie pytanie, czy użytkownicy doceniliby wartość posiadania tablicy params w jednym przeciążeniu, nawet jeśli nie byłoby jej we wszystkich przeciążeniach.

✔️ Spróbuj uporządkować parametry, aby umożliwić użycie słowa kluczowego params.

✔️ ROZWAŻ zapewnienie specjalnych przeciążeń i ścieżek kodu dla wywołań z niewielką liczbą argumentów w interfejsach API szczególnie wrażliwych na wydajność.

Dzięki temu można uniknąć tworzenia obiektów tablicowych, gdy interfejs API jest wywoływany z niewielką liczbą argumentów. Utwórz nazwy parametrów, przyjmując pojedynczą formę parametru tablicy i dodając sufiks liczbowy.

Należy to zrobić tylko wtedy, gdy zamierzasz potraktować całą ścieżkę kodu jako szczególny przypadek, a nie tylko utworzyć tablicę i wywołać bardziej ogólną metodę.

✔️ Należy pamiętać, że wartość null może zostać przekazana jako argument tablicy params.

Przed przetworzeniem należy sprawdzić, czy tablica nie ma wartości null.

❌ NIE należy używać varargs metod, znanych również jako wielokropek.

Niektóre języki CLR, takie jak C++, obsługują alternatywną konwencję przekazywania list parametrów zmiennych nazywanych varargs metodami. Konwencja nie powinna być używana w frameworkach, ponieważ nie jest zgodna ze specyfikacją CLS.

Parametry wskaźnika

Ogólnie rzecz biorąc, wskaźniki nie powinny pojawiać się w publicznej części dobrze zaprojektowanego systemu kodu zarządzanego. W większości przypadków wskaźniki powinny być enkapsulowane. Jednak w niektórych przypadkach wskaźniki są wymagane ze względów współdziałania, a użycie wskaźników w takich przypadkach jest odpowiednie.

✔️ Należy zapewnić alternatywę dla każdego elementu, który przyjmuje argument wskaźnika, ponieważ wskaźniki nie są zgodne ze specyfikacją CLS.

❌ UNIKAJ wykonywania kosztownego sprawdzania argumentów wskaźnika.

✔️ Należy przestrzegać typowych konwencji związanych ze wskaźnikiem podczas projektowania elementów członkowskich ze wskaźnikami.

Na przykład nie ma potrzeby przekazywania indeksu początkowego, ponieważ prosta arytmetyka wskaźników pozwala osiągnąć ten sam wynik.

© Części 2005, 2009 Microsoft Corporation. Wszelkie prawa zastrzeżone.

Przedrukowane za zgodą Pearson Education, Inc. z Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition przez Krzysztofa Cwalinę i Brada Abramsa, opublikowane 22 października 2008 przez Addison-Wesley Professional w ramach serii Microsoft Windows Development.

Zobacz także

• Wytyczne dotyczące projektowania członów konstrukcji
• Wytyczne dotyczące projektowania struktury