Znaczące zwięzłe wytyczne dotyczące nazewnictwa metod

Niedawno zacząłem wypuszczać projekt open source, będąc jedynym użytkownikiem biblioteki, nie dbałem o nazwy, ale wiem, że chcę przypisać sprytne nazwy do każdej metody, aby ułatwić naukę, ale muszę też użyć zwięzłe nazwy, aby były łatwe do napisania.

Myślałem o kilku wytycznych dotyczących nazewnictwa, zdaję sobie sprawę z wielu wskazówek, które dbają tylko o wielkość liter lub kilka prostych notatek. Tutaj szukam wskazówek dla sensownego, ale zwięzłego nazewnictwa.

Może to być na przykład część wytycznych, o które dbam:

• Użyj Dodaj, gdy istniejący element zostanie dodany do celu, Użyj Utwórz, gdy nowy element zostanie utworzony i dodany do celu.
• Użyj Usuń, gdy istniejący element zostanie usunięty z celu, Użyj usuń, gdy element zostanie trwale usunięty.
• Sparuj metody AddXXX z metodami RemoveXXX i Sparuj metody CreateXXX z metodami DeleteXXX, ale nie mieszaj ich.

Jak pokazują powyższe przykłady, chciałbym znaleźć trochę materiałów online, które pomogą mi w metodach nazewnictwa i innych elementach zgodnych z gramatyką angielską i znaczeniami słów.

Powyższe wskazówki mogą być intuicyjne dla rodzimych użytkowników języka angielskiego, ale dla mnie, że angielski jest moim drugim językiem, muszę powiedzieć o takich sprawach.

Nazewnictwo. Jedna z najtrudniejszych rzeczy w tworzeniu oprogramowania :)

Kiedy coś nazywam, oto mój zestaw priorytetów:

• Postępuj zgodnie z idiomami mojego języka. Ruby lubi podkreślenia. JavaScript lubi obudowę wielbłąda. Niezależnie od tego, w jakim języku jesteś, należy przestrzegać konwencji.
• Ujawnia zamiar API. To nie jest „send_http_data”, to „post_twitter_status”
• Unikaj nieszczelnych szczegółów implementacji. Powiedzmy, poprzedzając zmienną typem.
• Nie używa więcej znaków niż to konieczne bez złamania poprzednich wytycznych.

Oczywiście jest to dość uproszczone podejście. Nazewnictwo jest dopracowane.

Do dalszych badań zaleciłbym przeczytanie The Art of Readable Code , ponieważ zawiera on doskonałe, zwięzłe porady dotyczące nazewnictwa metod. Do dalszych badań nie mogę bardziej polecić Clean Code Boba Martina

Pokusa skodyfikowania stylu lub konwencji nazewnictwa może w niektórych przypadkach prowadzić do nawyków, które są obecnie uważane za złe praktyki, takie jak na przykład używanie notacji węgierskiej. Prostą odpowiedzią jest zapomnienie o konwencji i stylu nazewnictwa, jakby to była osobna rzecz do ustalenia osobno, a zamiast tego skupienie się na nazywaniu wszystkiego w systemie na podstawie tego, co faktycznie reprezentuje. Nazwy metod będą naturalnie zwięzłe, jeśli ograniczysz funkcjonalność każdej z metod, tak aby robiło to tylko jedno pojęcie, a jeśli nazwa metody faktycznie opisuje jedną rzecz, którą ma wykonać metoda.

Zmienne, pola, nazwy klas i plików to coś innego. Sugerowałbym, że jeśli nazwy zmiennych stają się zbyt długie, to próbujesz albo opisać te elementy zbyt szczegółowo, albo reprezentują coś złożonego, który powinien być podzielony na mniejsze części, lub być może opisany bardziej abstrakcyjnie sposób.

Na koniec dnia chcesz uniknąć brzydkiego kodu z nazwami, które zajmują cały wiersz lub są tak płynne, że pozbawiają je wartości.

Dla mnie znalezienie dobrego imienia dla czegoś zawsze wraca do myślenia o nim jako o obiekcie, który musi uzasadniać jego istnienie. Zapytaj siebie:

• Do czego służy klasa / metoda / zmienna, tj. Jaki jest jej szerszy cel i do czego służy?
• Co konkretnie w swoim celu musi się komunikować, tj. Jaka jest zasadnicza część, jaką musi mieć w sobie nazwa?

Większość programistów zgodzi się, że czytelność ma zawsze ogromne znaczenie, jeśli chodzi o nazewnictwo. Nie pisz po prostu kodu, abyś wiedział, co masz na myśli, pisząc go, napisz go tak, aby ktoś, kto zobaczy kod po raz pierwszy w pewnym momencie w przyszłości, wiedział, co masz na myśli, bez zbytniego zastanawiania się. Kod napiszesz tylko raz, ale w trakcie jego trwania najprawdopodobniej będzie musiał być edytowany wiele razy i czytany jeszcze więcej razy.

Kod powinien być samodokumentujący, to znaczy, że twoje nazewnictwo powinno wyraźnie pokazywać, co coś robi. Jeśli musisz wyjaśnić, co robi wiersz kodu w komentarzu, a zmiana nazwy rzeczy nie poprawia go wystarczająco, powinieneś poważnie rozważyć przekształcenie tego wiersza w nową metodę o odpowiednio opisowej nazwie, tak aby po przeczytaniu oryginalnej metody nowe wywołanie metody opisuje, co się dzieje. Nie bój się mieć długich nazwisk; oczywiście nie powinieneś pisać powieści w nazwach klas / metod / zmiennych, ale wolałbym, aby nazwa była za długa i opisowa niż za krótka i muszę dowiedzieć się, co robi, patrząc pod maską. Z wyjątkiem pewnych oczywistych wyjątków, takich jak współrzędne x / y i często używane akronimy, unikaj nazw i skrótów jednoznakowych. Nazywanie czegoś „bkBtn” zamiast „backButton”

O ile pozwala na to Twój język, spraw, aby Twój kod był czytany jak zdanie angielskie. Obiekty używają rzeczowników, metody używają czasowników. Metody boolowskie zwykle zaczynają się od „jest”, ale istnieje wiele innych opcji, które przekazują znaczenie jeszcze lepiej, w zależności od przypadku użycia, takich jak „może”, „powinien” lub „robi”. Oczywiście nie wszystkie języki mogą być w tym języku tak dobre, jak Smalltalk, ale niektóre symbole są ogólnie rozumiane jako części zdania. Dwie konwencje Smalltalk, które osobiście lubię brać pod uwagę w innych językach, na tyle, na ile to możliwe, poprzedzają nazwy parametrów pętli słowem „każdy”, a parametry metody przedrostkiem tekstem „a” (lub „an” lub „niektóre” w przypadku kolekcji) . To może nie być powszechny standard w Javie i każdy może zignorować ten bit, ale uważam, że znacznie poprawia to czytelność kodu. Na przykład (przykład w Javie):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Powinno to być czytelne dla osób z niewielką znajomością języka Java, takich jak:

Aby ustalić, czy należy rozważyć skrócenie listy niektórych nazw (które są ciągami znaków), iteruj po niektórych nazwach i dla każdej nazwy określ, czy jest ona za długa; jeśli tak, wróć true; jeśli żadna nie jest za długa, wróć false.

Porównaj powyższy kod z samą nazwą argumentu stringsi zmiennej pętli string, szczególnie w bardziej złożonej metodzie. Trzeba było przyjrzeć się bliżej, aby zobaczyć różnicę zamiast oczywistego użycia na pierwszy rzut oka.

Znalezienie dobrego nazewnictwa jest zawsze kompromisem między większą liczbą czynników. Nigdy nie będziesz w pełni zadowolony.

To powiedziawszy, nawet jeśli twój język ojczysty nie jest w ten sposób, weź pod uwagę, że angielski jest językiem, którego tokeny języków programowania są tworzone. Korzystanie ze składni angielskiej sprawia, że ​​czytanie kodu jest bardziej „płynne”, ponieważ nie ma „złamanych reguł czytania” przy każdym znalezieniu słowa kluczowego.

Ogólnie rzecz biorąc, rozważ takie rzeczy jak object.method(parameters)dopasowanie do schematu subject.verb(complements).

Kluczową kwestią, jeśli musisz wspierać ogólne programowanie, jest wybór dobrego i spójnego zestawu „czasowników” (szczególnie tych, które muszą być używane w ogólnych algorytmach).

O rzeczownikach klasy powinny być nazwane po to, co one are(pod względem koncepcji), a obiekty za to, co one are for.

To powiedziawszy, pomiędzy list.add(component)i component.add_to(list)wolę pierwszy. Ogólnie rzecz biorąc, czasowniki „przechodnie aktywne” lepiej reprezentują działania względem ich pasywnych lub zwrotnych odpowiedników. O ile nie ograniczają Cię konstrukcje.

Nie martw się o długość nazw metod. Upewnij się, że nazwy metod wyraźnie odzwierciedlają to, co robią. Jest to nadrzędne w stosunku do wszystkiego innego. Jeśli uważasz, że nazwa metody jest za długa, użyj tezaurusa, aby znaleźć krótsze słowo, które oznacza to samo. Na przykład użyj Findzamiast Retrieve.

Równie ważne są nazwy, które wybierzesz na zajęcia. Zapewniają one duży kontekst podczas patrzenia na nazwy metod. Podpis metody:

public User Find(int userId);

jest łatwiejszy do zrozumienia niż:

public Person Find(int personId);

ponieważ kontekst uzyskany z nazwy klasy Usermówi programiście, który Find()ma za zadanie zlokalizować określony typ osoby, użytkownika twojego systemu. Wersja korzystająca z tej Personklasy nie daje żadnego kontekstu na temat tego, dlaczego w ogóle musiałabyś użyć tej metody.

Zobacz, jak robią to inni na Twojej platformie - niektórzy z większych graczy mogą mieć nawet styl kodu i wskazówki dotyczące nazewnictwa.

Niektóre platformy wolą krótkie nazwy (na przykład, w API Win32 C API _tcsstrjest funkcja znajdowania ciągu w ciągu - nie jest to oczywiste?), Inne preferują czytelność na rzecz zwięzłości (w frameworku Cocoa firmy Apple dla Objective-C , metoda zamiany podłańcucha w łańcuchu na inny i zwrócenia wyniku, gdy wywoływana jest kopia stringByReplacingOccurrencesOfString: withString:). Uważam, że ta ostatnia jest znacznie łatwiejsza do zrozumienia i tylko umiarkowanie trudniejsza do napisania (szczególnie przy uzupełnianiu kodu).

Ponieważ czytasz kod częściej niż go piszesz (podwójnie prawda w przypadku bibliotek typu open source), a czytanie jest trudniejsze niż pisanie, zoptymalizuj go pod kątem czytania. Zoptymalizuj tylko dla zwięzłości i zabierz tyle, ile to możliwe, bez osłabiania przejrzystości.

1. Załóżmy, że angielski, chyba że każdy programista, który kiedykolwiek pracuje nad tym kodem, będzie mówił tym samym językiem innym niż angielski.

2. Przestudiuj powszechnie przyjęte konwencje i style nazewnictwa. Waszą naczelną zasadą powinna być jasność. Style różnią się w zależności od języka programowania.

3. Nie można nic zrobić z nazewnictwem, co ułatwi zrozumienie relacji między różnymi obiektami w kodzie. W tym celu nadal potrzebujesz dobrze napisanych komentarzy i dokumentacji.

1. Użyj prefiksu. Jeśli do zrobienia czegoś podobnego zastosowano kilka metod lub można je w jakiś sposób pogrupować, przed ich nazwami umieść wspólny przedrostek, aby pokazać, co te metody mają ze sobą wspólnego.
2. Nie używaj niejasnego skrótu, jeśli chcesz, aby inni natychmiast zrozumieli nazwy (ważne w nazewnictwie API)