Coding standards, cz. 1 – konwencje nazewnictwa
Zapraszam na pierwszą część zapowiedzianego cyklu „coding standards”. Będzie ona poświęcona konwencji nadawania nazw.
Pamiętacie PHP? Niemal każdy z nas przez to przechodził. Nie ma chyba drugiego języka programowania, który oferuje taką ilość gotowych funkcji, realizujących najdziwniejsze nawet zadania. Nie ma też niestety drugiego języka, który ma tak niekonsekwentne nazewnictwo[1]. Jak się przed tym uchronić w naszym kodzie? Bez zbędnych szczegółow – oto zasady, które pozwolą na łatwiejsze zrozumienie kodu i sprawniejsze poruszanie się w nim przez szersze „grono”:
1. Używaj angielskiego nazewnictwa
Tutaj chyba nie jest potrzebne żadne wyjaśnienie. Miałem okazję pracować przy projekcie, w którym nazwy klas i funkcji były pisane po polsku. Momentami było wesoło – gdy np. twócy brakowało inwencji napotykało się kwiatki w stylu GetKsiazkiList – nie życzę jednak nikomu ;-)
2. Używaj PascalCase oraz CamelCase
PascalCase, czyli pierwsza litera każdego słowa jest duża, np: PersonName
Stosowany do nazywania: klas, typów enum, wartości enum, zdarzeń, stałych pól, pól tylko do odczytu, interfejsów, metod, namespace’ów oraz property i nazw plików.
CamelCase, czyli litera pierwszego słowa mała, pierwsze litery kolejnych słów duże, np: listCount
Stosowany do nazywania: pól, parametrów w metodach oraz zmiennych lokalnych.
3. Nie używaj notacji Węgierskiej
Wymyślił to człowiek z Microsoftu a teraz Microsoft uważa to za passe ;-) Zmiana typu zmiennej wiąże się ze zmianą wszystkich jej wystąpień w programie. Masakra. Zapis _fieldName również uważany jest za notację węgierską, jednak używam właśnie tego zapisu dla oznaczenia prywatnych pól w klasie. Taki mały, wygodny wyjątek.
4. Nie używaj wielkości liter do rozróżnienia identyfikatorów
O ile dla C# zmienna myVariable oraz myvariable to dwie różne rzeczy, o tyle nie jest to zapis zgodny z CLS (Common Language Specification) i kod, który zawiera podobne cuda, nie będzie nigdy mógł być współdzielony np. w aplikacji napisanej w VB (gdyż VB nie rozróżnia wielkości liter).
5. Nie dodawaj przyrostków klasom, strukturom, typom enumerowanym
Bo i po co? Czy komuś pomoże w zrozumieniu programu nazwanie klasy PersonClass zamiast Person lub LogTypeEnum zamiast LogType? Wątpliwe, nadmiarowe, nieładne i niepotrzebne.
6. Nie używaj liter, które moga być pomylone z cyframi (i odwrotnie)
Naprawdę potrzeba przykładu ;-) ? Ok:
7. Do klas wyjątków dołączaj przyrostek
Tutaj dodawanie postfiksu jest wskazane, np. ApplicationException, MyCustomException.
9. Używaj skrótów. Z głową!
Skracaj nazwy – kod będzie czytelniejszy. Rób to jednak z głową. Dobrze znane, ogólnie rozumiane skróty (jak np. LoadUI – UI od UserInterface) są wskazane, jednak konstrukcje typu GetComp zamiast GetComponent… czy za miesiąc sam będziesz pamiętał do czego to było?
10. Parametry nazywaj zgodnie z ich znaczeniem, funkcją – nie typem.
void Add(int value1, int value2) { ... }
Które wg Ciebie czytelniejsze?
11. Namespace’y – używaj ogólnie przyjętego wzorca
Jego struktura to: [firma].[technologia].[komponent nadrzędny].[komponent niższego rzędu], np:
AndrzejCompany.Framework.WebHelpers.Tools
12. Klasy nazywaj używając rzeczownika w liczbie pojedynczej
Klasa ma się nazywać Member, nie Members.
13. Nazwy interfejsu poprzedzaj dużą literą I, sam interfejs określaj przymiotnikiem
Ma to służyć łatwemu odróżnieniu interfejsu od zwykłej klasy. Przymiotnik dlatego, że interfejs ma implementować określone zachowanie, stąd w CLR nazwy: IComparable, ICloneable itd.
14. Dodawaj określenie EventHandler do delegatów powiązanych ze zdarzeniami
Np.
15. Do nazwania zdarzeń (events) używaj czasowników
Np.
16. Zachowuj spójność nazwy klasy i jej pliku, ograniczaj ilość klas w pliku
Np. klasa Person powinna zawierać się w pliku Person.cs. Staraj się nie definiować więcej niż jednej klasy (z zaprzyjaźnionymi, klasami, typami Enum) w jednym pliku. Większe klasy oznacz jako partial i podziel logicznie na kilka plików.
To wszystko, co udało mi się uporządkować z własnych praktyk oraz przykładów i zaleceń znalezionych przy okazji zgłębiania tematu w internecie.
Zapraszam do dyskusji.
Przypisy
- wspomnieć najpopularniejsze choćby: strip_tags i stripslashes – raz z underscorem, raz bez. Intuicyjne jak cholera ;-) ↩
Podobne wpisy
Coding standards, cz. 2 – ogólne zasady pisania dobrego kodu
Coding standards – intro
Możesz śledzić odpowiedzi do tego wpisu za pomocą RSS 2.0 feed. Możesz leave a response, or trackback z Twojej własne strony.
Coding standards, cz. 1 – konwencje nazewnictwa | Blog o programowaniu C#, ASP.NET…
Dziękujemy za publikację – Trackback z dotnetomaniak.pl…
Jeśli chodzi o nazwy to teoretycznie jest to lepszy pomysł, by używać angielskich nazw, ale jak nazwać np. formatkę do naboru kandydatów, do nadzoru, do wniosków opłat itp. Ciągłe tłumaczenie nazw przy pomocy translatora daje nadzwyczaj zabawne rezultaty – szczególnie dla osób znających dobrze angielski.
tez zawsze uzywam angielskich nazw, utwierdzilem sie w tym procederze ;) jeszcze bardziej gdy przyszlo mi pracowac z baza danych tworzona przez niemieckich programistow. Wiecie jak jest tabela personalna? Mitarbeiter… A z dzialami? Abteilung.
Sa jeszcze inne nazwy, niektore slowa maja nawet 20 znakow i nic z nich nie kumam. Masakra.
Podstawa to uzywac angielskiego ktory w obecnym swiecie jest uwazany za jezyk ogolno przyjety dla prac naukowych itp. (tak jak kiedys lacina a w przyszlosci chinski ;)))
@michal: „np. formatkę do naboru kandydatów, do nadzoru, do wniosków opłat itp. ”
wystarczy ze dodasz ze 2 „slowa klucze” w nazwie i juz bedzie o niebo bardziej zrozumiale dla kogos obcojezycznego niz polskie nazwy i to bez znakow diakrytycznych.
Artykul fajny, moze tylko rozszerzyc go jeszcze w dalszych czesciach o prefixy dla kontrolek.
Ja osobiscie stosuje:
lb Label
tb TextBox
ci Checkbox
btn Button
ale przy rzadziej uzywanych mam czesto dilema ;)
Pozdr.
@michal, jesli to kontrolki ascx ja nazwalbym je np: Recrutation, Supervision itd. Chodzi o to aby się kojarzyły. Jeśli to będą ascx lub formatki windows forms – raczej każdy załapie o co chodzi. Nie trzeba dodawać RecruationControl czy RecrutationForm – to wynika z kontekstu IMHO ;-)
@binary, o widzisz, przeoczyłem faktycznie prefixy kontrolek :) osobiście trochę inaczej je stosuje – nie wiem w sumie skąd to się wzięło ale w firmie, w której pracuję chyba wszyscy robią dokładnie tak samo :
lbl Label
tb TextBox
chk Checkbox
ddl DropDownList
btn Button
imgb ImageButton
ph PlaceHolder
p Panel
Uzbieram jakiś komplecik, poszukam jak robią to inni i rozszerzę artykuł. Dzięki za opinie.
Zgadzam sie ze wszystkimi punktami, oprocz interfejsow. Ja bym wywalil literke I (wszak to czysto wegierska notacja), niestety MS poszedl ta droga i wszyscy ciagna tak samo dalej.
Np:
void PrintAll(List persons)
wyglada duzo lepiej niz
void PrintAll(IList persons)
bo po co mi w tym miejscu informacja ze List to interfejs (poza tym VS potrafi kolorowac interfejsy inaczej niz inne identyfikatory)?
Co do prefixowania kontrolek skrotami lb cb itd. to tez mi to sie nie podoba. Duzo lepiej uzywac prefiksu obiektu do ktorego sa przypisane kontrolki lub thisa np:
string name = personForm.name;
string name = this.name;
Widziałem ostatnio kod gdzie osobą tak bardzo zasugerowała się tym co było przykładowo podane w książce, że do każdej klasy i metody dodawała przedrostek My.. np. MyLoad, MyTools, MyPobierzDane i wszystko było „My”.