Czy istnieją dobre techniki lub testy dla nazewnictwa typów?

Niezręczne, otwarte pytanie, ale to problem, z którym zawsze się spotykam:

Oprogramowanie, które jest łatwe w utrzymaniu i obsłudze, jest dobrze zaprojektowane. Próba uczynienia projektu intuicyjnym oznacza nazywanie komponentów w taki sposób, aby następny programista mógł móc wywnioskować ich działanie. Dlatego nie nazywamy naszych klas „Type1”, „Type2” itp.

Podczas modelowania koncepcji rzeczywistej (np. Klienta) jest to na ogół tak proste, jak nazywanie swojego typu po modelowaniu koncepcji rzeczywistej. Ale kiedy budujesz abstrakcyjne rzeczy, które są bardziej zorientowane na system, bardzo łatwo zabraknie imion, które są zarówno łatwe do odczytania, jak i łatwe do strawienia.

Gorzej (dla mnie), gdy próbuję nazwać rodziny typów, z typem bazowym lub interfejsem, który opisuje, co muszą zrobić komponenty, ale nie sposób ich działania. To naturalnie prowadzi do każdego typu pochodzącego próbuje opisać smak realizacji (np IDataConnectionoraz SqlConnectionw .NET Framework), lecz jak można wyrazić coś skomplikowane jak „działa przez odbicie i szuka konkretnego zestawu atrybutów”?

Potem, kiedy już w końcu wybrał nazwę typu uważasz opisuje to, co próbuje zrobić, twój kolega pyta „WTF czy to DomainSecurityMetadataProviderfaktycznie zrobić? ”

Czy są jakieś dobre techniki wyboru dobrej nazwy dla komponentu lub jak zbudować rodzinę komponentów bez uzyskiwania mętnych nazw?

Czy są jakieś proste testy, które mogę zastosować do nazwy, aby lepiej wyczuć, czy nazwa jest „dobra” i czy powinna być bardziej intuicyjna dla innych?

Jeśli chodzi o nazewnictwo, sprawdzono dla mnie sześć technik :

1. spędzać dużo czasu na wymyślaniu nazwisk
2. użyj recenzji kodu
3. nie wahaj się zmienić nazwy
4. spędzać dużo czasu na wymyślaniu nazwisk
5. użyj recenzji kodu
6. nie wahaj się zmienić nazwy

PS. W przypadku, gdy Twój interfejs API będzie publiczny, powyższe ma zastosowanie wcześniej - ponieważ wiesz,

„Publiczne interfejsy API, takie jak diamenty, są wieczne. Masz jedną szansę, aby zrobić to dobrze, więc daj z siebie wszystko ...” (Joshua Bloch, Jak zaprojektować dobry interfejs API i dlaczego to ma znaczenie )

Mój test podstawowy polega na tym, czy możesz opisać funkcję zmiennej, używając tylko słów ze zmiennej:

np. jeśli DomainSecurityMetadataProvider „Dostarcza metadane bezpieczeństwa domeny” lub „Dostarcza metadane związane z bezpieczeństwem domeny”, to dobrze.

Istnieją jednak niuanse, które różnią się w zależności od osoby:

np. dla mnie original_team_code jest kodem dla oryginalnego zespołu, podczas gdy dla kogoś innego może być oryginalnym kodem dla zespołu. Moim osobistym ulubionym z nich był „UnsafeLegacyMutex”, którego nie mogłem powstrzymać przed przeczytaniem jako „To jest Legacy Mutex, który jest niebezpieczny”, a nie „To jest Mutex dla ThreadUnsafe Legacy Code”.

Więc moim rozszerzonym testem jest zapisanie zmiennej na tablicy / wiki / chat i niech ludzie zgadną, co to znaczy.

Czy są jakieś dobre techniki wyboru dobrej nazwy dla komponentu lub jak zbudować rodzinę komponentów bez uzyskiwania mętnych nazw?

Nie całkiem.

Jedną wskazówką jest jednak unikanie „głosu pasywnego”.

„DomainSecurityMetadataProvider” jest pasywny. Nie ma czasownika, wszystkie rzeczowniki i rzeczowniki są używane jako przymiotniki.

„ProvideMetadataForDomainSecurity” jest bardziej aktywne. Jest czasownik.

Programowanie obiektowe to wszystko (naprawdę) czasownik. Rzeczownik == obiekt. Czasownik == metoda. Tak więc nazwa klasy jest na ogół bardzo „rzeczownikowa”. Przełamanie tego nawyku i rozpoczęcie wstawiania czasowników jest trudne.

Czy są jakieś proste testy, które mogę zastosować do nazwy, aby lepiej wyczuć, czy nazwa jest „dobra” i czy powinna być bardziej intuicyjna dla innych?

Tak. Zdefiniowałeś doskonały test w swoim pytaniu. Zapytaj innych ludzi.

W dawnych czasach nazywaliśmy to „poradnikiem projektowym”. To była wielka, spocona transakcja w metodyce wodospadu. W dzisiejszych czasach, dzięki metodom zwinnym, powinna być zwykła współpraca między autorem a użytkownikami klasy. To nie zajmuje (i nie powinno) długo. Omówienie projektu (i nazw) przed napisaniem testów (i kodu) zmniejszy czynnik zdziwienia i może zapobiec WTF.

Korzystanie z tezaurusa

Bardzo często będę odnosił się do tezaurusa, kiedy robię nowy rozwój, aby znaleźć odpowiednie słowa do opisania moich klas i metod.

Klasy, które przede wszystkim zawierają logikę operacji

Zazwyczaj nazywam klasy, które przede wszystkim zapewniają metody działania w strukturze czasownikowej, np. „EntityProvider”, „EntityLocator” itp.

Te klasy na ogół nie zawierają dużo stanu.

Klasy zawierające stan

Ekrany interfejsu użytkownika i jednostki danych są na ogół stanowe, więc po prostu nazywam te klasy wzorcem rzeczownikowym lub przymiotnikowo-rzeczownikowym.

Przykłady: osoba, pracownik, obecny pracownik, były pracownik

Klasy użyteczności

Klasy, które zawierają tylko metody statyczne, są ogólnie uważane za klasy „użytkowe”, więc konsekwentnie nazywam je sufiksem „Użyteczność”.

Przykłady: NetworkUtilities, FileUtilities

Testy

Nie mam dobrych testów pozwalających stwierdzić, czy coś jest źle nazwane, ale sugerowałbym, aby spróbować użyć pojedynczego rzeczownika i / lub pojedynczego czasownika w nazwie, a następnie zastanowić się, czy rzeczownik / czasownik dokładnie opisuje to, co „ zmiana nazwy.

Jeśli uważasz, że w klasie / metodzie jest coś więcej, co nie jest przechwytywane przez nazwę, wówczas może być konieczne ponowne przetworzenie tej klasy / metody.

Alan Green i Jeff Attwood pisali o złu nazywania klas za pomocą sufiksu „Manager”. Twierdzą, że termin „menedżer” jest nadużywany i jest zbyt niejasny, aby przekazać coś sensownego. Muszę się zgodzić.

Artykuł Jeffa zawiera także listę sugerowanych wskazówek z Kodeksu ukończonego przez Steve'a McConnella.

zmienne

Ostatnio eksperymentowałem z dłuższymi opisowymi nazwami zmiennych / parametrów, które zawierają przyimki, takie jak „Of”, „By”, „For” itp. Niektóre przykłady pokazano poniżej:

string firstNameOfEmployee;

string lastNameOfEmployee;

// here I nimbly avoid worrying about whether to call it "Id" or "ID" :)
int idOfEmployee;

decimal amountForDeposit;

Account accountForDeposit;

Uważam, że działa to dobrze z funkcją inteligencji Visual Studio, która ułatwia wpisywanie tych długich nazw. Zauważyłem również, że mniej powielania prefiksów nazw zmiennych (np. PersonID, personFirstName, personLastName vs. idOfPerson, firstNameOfPerson, lastNameOfPerson), zapewniając lepsze „hash”, dzięki czemu intellisense jest jeszcze bardziej użyteczny.

Następnie, kiedy w końcu wybrałeś nazwę typu, który Twoim zdaniem opisuje, co próbuje zrobić, twój kolega pyta: „WTF naprawdę robi to DomainSecurityMetadataProvider?”

Jakiej nazwy oczekujesz dla klasy złożonej i specyficznej dla domeny? Jest to tak dobre, jak to będzie możliwe, bez nadawania nazwy klasie zdania (co sprawi, że wszyscy będą myśleć, że zbyt wiele odpowiedzialności spoczywa na jednej klasie)

Rozważę usunięcie dostawcy z nazwy. Jeśli konkretnie wspomina o metadanych, wszyscy już wiedzą, że używasz refleksji. Możesz sprawić, by jedno słowo było bardziej zwięzłe (lub ewentualnie zmienić na inne słowo - jest bardziej konsumentem niż dostawcą z tego, co napisałeś)

Użyj metafor do opisania części systemu. Nie tylko pozwoli ci odkryć nowe analogie, ale także ułatwi nazewnictwo.

(Wiem, że to nie jest mocny przykład, ale mimo to) Na przykład możesz wywołać zmienną lub typ as mailbox, który służy jako kolejka dla odebranych wiadomości dla klasy.

Jedną rzeczą, na której jestem bardzo stanowczy, jest to, że NIGDY nie powinno się dopuszczać do niepoprawności. Najlepszy przykład, podczas niektórych przefakturowań wiele się zmieniło, a kilka zmiennych zaczęło odnosić się do czegoś innego niż sugerowały ich nazwy.

Wkrótce jeden programista spędził wiele lat i korzystał z bardzo drogich wywołań bazy danych, próbując zdobyć pewne dane, które zostały już wyodrębnione i zapisane. Zmieniłem nazwę wszystkiego i nagle mogliśmy usunąć tonę skomplikowanej i błędnej logiki.

Mam nadzieję, że przypadki, w których trzeba tak mocno myśleć o nazwiskach, są rzadkie. Gdy pojawią się takie przypadki, po prostu napisz akapit wyjaśniający, co robi klasa. W przeciwieństwie do komentarzy w funkcji lub komentarza na poziomie funkcji, główny cel klasy rzadko się zmienia, więc ryzyko przedawnienia komentarzy jest stosunkowo niewielkie. Masz więc luksus pisania kilku akapitów lub nawet rysowania ASCII, aby wyjaśnić, co robi klasa.