piątek, 27 lipca 2012

Rzeczy po imieniu nazywać

nie o formie, a o treści

Jest wiele artykułów na temat nazewnictwa i z przykrością stwierdzam, że i ja go poruszę:) Zdaję sobie sprawę, że dla niektórych Was temat jest prosty, ale uważam, że jest to na tyle istotna rzecz, że warto poświęcić jej choć jeden wpis.

Chciałem jeszcze na wstępie zaznaczyć, że nie będę zajmował się tym, czy w nazwach powinniśmy używać podkreśleń, czy też wielkich liter, czy wszystko powinno być pisane ciągiem itp. Tu już wszystko zależy od polityki firmy i konwencji (bądź jej braku) przyjętych w danym języku programowania.

stałe

Ok, miało nie być o sposobie zapisu, ale stałe są na tyle charakterystycznymi elementami języków programowania i właściwie w każdym jest taka sama konwencja, więc - stałe powinny być pisane wielkimi literami:)
Ale co powinno być nazwą stałej? Rzeczownik określający to, czego dotyczy stała. Czasami zdarza się, że nazwa stałej jest nazwą własną pewnego bytu (np. PI).

atrybuty

Tak jak i stałe, powinny być rzeczownikami, niekiedy z dopełniającym go przymiotnikiem. W tym jednak wypadku nie powinna być to nazwa własna. Dlaczego? Ponieważ nazwa własna jest to raczej wartość pewnego atrybutu, a nie jego nazwa. Jeżeli w Waszym kodzie zdarzy się, że będzie Was taka nazwa kusiła, to warto pomyśleć jeszcze raz nad tym, czy projekt jest dobry.

metody

Metody opisują czynność, bo czym innym są metody, jeżeli nie ciągiem instrukcji, które są wykonywane? To jest działanie, a do jego określenia (nazwania) powinniśmy używać czasowników.

widoczność metod

Warto się zastanowić nad zróżnicowaniem zapisu dla metod publicznych oraz dla chronionych i prywatnych. Osobiście uważam, że zapis chronionych i prywatnych nie musi się różnić (w końcu obie widoczności informują nas o tym, że mamy dostęp do metody jedynie wewnątrz klasy lub jej potomka), jednak dobrą praktyką jest wyróżnienie metod publicznych.

widoczność atrybutów

Tu moim zdaniem dobrze trzymać się konwencji, którą wybrało się w stosunku do metod. Z drugiej jednak strony atrybuty publiczne są tak rzadko używane (a przynajmniej tak powinno być:) i zazwyczaj w dość charakterystycznych sytuacjach, że specjalne poświęcanie czasu na różnicowanie sposobu zapisu w zależności od widoczności, jest jego (czasu) stratą.

i jeszcze o widoczności

Pamiętajcie, że różnica powinna być subtelna np. dodanie znaku '_' przed nazwami metod i atrybutów chronionych i prywatnych. W innym wypadku, zamiast sprawić, że kod stanie się czytelniejszy, możecie go przez przypadek zaciemnić.

nazwy klas

Tutaj nazewnictwo powinno być takie, jak w przypadku atrybutów. Klasa to byt, a zatem rzeczownik. Niekiedy jednak warto dodać przymiotnik w celu jej sprecyzowania np. FastQuery.

interfejsy i klasy abstracyjne

Często mają takie same nazwy jak klasy. Warto jednak w jakiś sposób je wyróżniać np. litera i/a przed nazwą, słowo Interface/Abstract na jej końcu itp., aby już na pierwszy rzut oka było wiadomo z czym mamy do czynienia.

I jeszcze chwila na temat interfejsów:) Często są tworzone po to, aby zapewnić, że implementujące klasy będą posiadały pewną 'umiejętność' np. bieganie (run), wtedy warto rozważyć nazwanie go np. Runable, żeby pokazać, co tak naprawdę zapewnia jego implementacja. W tym przypadku użycie przedrostka czy innego wyróżnika wydaje mi się zbędne, ale to moje osobiste zdanie:)

na koniec

Mimo tego, że na wstępie zastrzegałem się jakiegokolwiek pisania na temat formy nazywania, to chciałbym ze swojej strony doradzić jedną rzecz.
Jeżeli jeszcze nie macie własnego stylu pisania, to siądźcie, przejdzie przez powyższe akapity i zastanówcie się, jak Wy będziecie oznaczać poszczególne elementy Waszego kodu.
Jeżeli pracujecie w firmie, gdzie projekty są jednoosobowe i każdy pisze tak, jak mu się podoba, to również poświęćcie chwilę i wspólnie zastanówcie się nad wspólną konwencją. To ułatwi Wam życie w przyszłości.
Dobrym pomysłem jest spisanie tego wszystkiego i udostępnienie dokumentu każdej zainteresowanej osobie.

Poza tym, decydując się na jakąkolwiek formę, warto zapoznać się ze sposobem, w jaki są pisane popularne biblioteki danego języka, może jest jakaś konwencja? Po co wymyślać na nowo coś, co już zostało wymyślone?

7 komentarzy:

  1. Widoczność metod
    "jednak dobrą praktyką jest wyróżnienie metod publicznych."
    tzn?

    OdpowiedzUsuń
    Odpowiedzi
    1. Chodzi mi o sam sposób nazywania np. metody prywatne i chronione - _doSomething(), metoda publiczna - doSomething().

      Usuń
    2. A po co, skoro IDE zazwyczaj dobrze sobie radzą zarówno z rozpoznawaniem "private/protected/public" jak i z komentarzami?

      Poza tym - skoro już ten temat poruszyłeś, mogłeś spreparować jakiś przykładowy kod i podpisać go "tak robić", "tak nie robić"

      Usuń
    3. Mogłem spreparować kod, ale wpis ma na celu podpowiedzieć, a nie sugerować.
      Z drugiej strony, tak jak napisałem, nie chciałem poruszać kwestii formy, a jedynie to, jakie informacje te nazwy powinny przekazywać. I jakie zabiegi można stosować, aby praca z kodem była przyjemniejsza.
      Realizacja tych rad, to już inna kwestia.

      Usuń
    4. Również uważam taki sposób wyróżniania metod prywatnych za zbędny.

      Usuń
  2. Polecam zapoznać się z
    https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
    i
    https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

    Pozdrawiam ;)
    Damian

    OdpowiedzUsuń
    Odpowiedzi
    1. Widziałem:)
      Tylko, że wpis nie traktuje o formie zapisu, ale o tym, co te nazwy powinny przekazywać. Po drugie, wpis nie jest o PHPie, a o językach obiektowych w ogóle:)

      Usuń