Struktura funkcji - nazewnictwo - zasada jednej operacji Opcje

[jackraymund]

Witam,
walczę z nazewnictwem

[PHP] pobierz, plaintext 
$companyId = $this->updateCompanySetToArrayAndGetId($matchedData['company']);//wywolanie
public function updateCompanySetToArrayAndGetId($aCompanyName)
	{
	$isCompanyExistInArray = in_array($aCompanyName,$this->companyArray);
	if(!$isCompanyExistInArray)
	  {
	  $companyId = $this->sqlUpdater->updateCompanyAndGetId($aCompanyName);
	  $this->companyArray[$companyId] = $aCompanyName;
	  return $companyId;
	  }
	else
	  return array_search($aCompanyName,$this->companyArray);
	}
[PHP] pobierz, plaintext 

Z zasady, jedna funkcja, jedna operacja,ten kod jest okropny, lecz zarazem nazwa tej funkcji jest okropna(pomijając tą zasadę).
Natomiast załóżmy że chciałbym zrobić to na tej zasadzie i zrobić to w miarę optymalnie.(chodzi o to, aby nie wywołać funkcji z sqlUpdater, gdy rekord znajduje się aktualnie w tablicy).

Jestem otwarty na wszelakie pomysły.

Pozdrawiam

[in5ane]

Chodzi Ci o samo nazewnictwo metod?

Jeśli np. cała klasa odpowiada za firmę/firmy (company Twoje), no to nazwij taką metodą poprostu update. I do tego masz przecież komentarze i tag @return, w którym możesz opisać, że zwraca dane typu integer, czyli ID firmy i tyle.

[NickOver]

@up Według mnie komentarzy powinno nie używać się w kodzie, nazwy funkcji lub metod powinny mówić wszystko.

[PHP] pobierz, plaintext 
private function prepareUpdateCompany($companyName){
if (!$this->isInArray($companyName){
$this->companyArray[$companyId] = $companyName;
return $this->sqlUpdater->updateCompanyAndGetId($companyName);
} else {
return array_search($aCompanyName,$this->companyArray);
}
 
private function isInArray($companyName){
return in_array($companyName,$this->companyArray);
}
[PHP] pobierz, plaintext 

BTW Rozumiem że to kod piany na szybko, przed faktoryzacją, ale albo używasz notacji węgierskiej albo nie.

[in5ane]

@up Według mnie komentarzy powinno nie używać się w kodzie, nazwy funkcji lub metod powinny mówić wszystko.

A od kiedy, to nie powinno się używać komentarzy w kodzie?

[Pyton_000]

Od zawsze
@NickOver miał na myśli komentowanie kodu samego w sobie, nie komentarze dla funkcji czy klasy bo to oczywiście obowiązkowe.

Komentowanie kodu to tylko ukrycie fatalnie napisanego kodu. Skoro ktoś pisze komentarz to znaczy że kod który napisał jest nieczytelny i nie da się wywnioskować w 2s. co on robi.
Dodatkowo komentarze się przedawniają. Mało kto dba o ich aktualizację podczas zmiany kodu.
Dlatego trzeba pisać kod jasny i czytelny aby na podstawie nazwy metody wiedzieć co ona robi bez zagłębiania się w kod. Jesli tak nie jest - jest fatalnie.

[in5ane]

@Pyton_000: jeśli o to chodziło, to racja. Sam, gdy piszę, to zawsze komentuję dokładnie metody oraz odpowiednio je nazywam i komentarz wewnątrz metod jest zbędny.

[Dejmien_85]

Od zawsze
@NickOver miał na myśli komentowanie kodu samego w sobie, nie komentarze dla funkcji czy klasy bo to oczywiście obowiązkowe.

Komentowanie kodu to tylko ukrycie fatalnie napisanego kodu. Skoro ktoś pisze komentarz to znaczy że kod który napisał jest nieczytelny i nie da się wywnioskować w 2s. co on robi.
Dodatkowo komentarze się przedawniają. Mało kto dba o ich aktualizację podczas zmiany kodu.
Dlatego trzeba pisać kod jasny i czytelny aby na podstawie nazwy metody wiedzieć co ona robi bez zagłębiania się w kod. Jesli tak nie jest - jest fatalnie.

Czy mnie się wydaje, czy tutaj ktoś czytał "Clean Code" Wujka Boba?

Ja od jakiegoś czasu czuję odrzucenie, gdy widzę phpdoki, w projektach które tego wymagają jest masa bezużytecznego tekstu, wszyscy generują automatycznie phpdoca, później dorzucają jakiś komentarz na szybko i tak się buduje git-majonez-dokumentacja, która wygląda następująca:

[PHP] pobierz, plaintext 
/**
* @var bankRepository
*/
$private bankRepository;
 
/**
* Gets account by user id
* @param $userId user id
* @return user account
*/
public function getAccountByUserId($userId) { ... }
[PHP] pobierz, plaintext 

I tak wygląda niestety większość komentarzy - DODAJĄ tyle informacji, że... WOW! No ale jak się wymaga phpdoca, to się jedzie ostro, wystarczy napisać metodę, później tylko stworzyć komentarz, nasze IDE wygeneruje phpdoca, na górze dopisujemy jakąś linijkę lub dwie i TA-DA, jesteśmy pr0-el0 developerzy, trzymający najwyższe standardy - tak jak nasza państwowa służba zdrowia. ; )

A a najlepsze są komentarze robione metodą typu "copy-paste", w których co jakiś czas znaleźć można jakieś małe kłamstewko - bo komuś w ferworze tworzenia dokumentacji się zapomniało wprowadzić zmiany - i się nawet tym osobom nie dziwię, bo przecież kto zwraca uwagę na komentarze? Ja im nie ufam, one kłamią.

Napisanie komentarza to ostateczność, to porażka programisty w utworzeniu kodu, który jest przejrzysty.

"Clean code reads like well-written prose", Grady Booch.

Ten post edytował Dejmien_85 25.03.2015, 23:47:55

[com]

To ja polecam poczytać poco się to robi. Jak korzystasz z IDE to ułatwia Ci to prace bo na bazie ich budowana jest baza do podpowiadania np w takim phpstormie. Który nawet pięknie Ci powie że mu się coś w komentarzach nie zgadza. Przyznaj się po prostu że nie potrafisz z nich korzystać, a nie. Poza tym co za problem jedno polecenie w konsoli i komentarze usunięte.

[Dejmien_85]

To ja polecam poczytać poco się to robi. Jak korzystasz z IDE to ułatwia Ci to prace bo na bazie ich budowana jest baza do podpowiadania np w takim phpstormie. Który nawet pięknie Ci powie że mu się coś w komentarzach nie zgadza. Przyznaj się po prostu że nie potrafisz z nich korzystać, a nie. Poza tym co za problem jedno polecenie w konsoli i komentarze usunięte.

Skończ proszę z tym bełkotem, uszy cierpią. ; )

Porady z korzystania z podpowiedzi IDE możesz udzielać w dziale "Przedszkole", my tutaj mówimy o rzeczach innego poziomu, na które jak widać - mimo wielu "punktów" na forum - jesteś jeszcze za młody.

Ten post edytował Dejmien_85 26.03.2015, 00:05:25

[com]

o rzeczach innego poziomu

Bardzo bym chciał się dowiedzieć jakich w takim razie. I nie wyskakuj mi tu z siłowaniem się na poziom wiedzy...

[Dejmien_85]

Bardzo bym chciał się dowiedzieć jakich w takim razie. I nie wyskakuj mi tu z siłowaniem się na poziom wiedzy...

Ech, wystarczy spojrzeć do góry... no ale czego tutaj wymagać (od Ciebie). ; )

Kiedyś może natkniesz się na jakąś książkę Roberta C. Martina, albo innych myślących programistów - bo Tobie to raczej nie zdarza się za często myśleć, prawda? Dawanie setek (w 3 lata 2000 postów i ponad 200 punktów) porad młokosom wyrobiło w Tobie chyba jakieś przeświadczenie, że wszyscy potrzebują porad. Tak zakładam, skoro próbowałeś dawać porady jak się z IDE korzysta - obawiam się, że pomóc może Ci tylko jakaś intensywna terapia.

Ja lekarzem nie jestem, więc Ci niestety nie pomogę.

Ten post edytował Dejmien_85 26.03.2015, 00:31:12

[com]

Skoro przeczytałeś czysty kod chwała Ci za to ale skoro już o tym mowa:

Nie ma nic bardziej pomocnego i satysfakcjonującego, jak dobrze opisane publiczne API. Przykładem
tego może być standardowa biblioteka Java. Bez niej pisanie programów Java byłoby trudne,
o ile nie niemożliwe.
Jeżeli piszemy publiczne API, to niezbędne jest napisanie dla niego dobrej dokumentacji Javadoc.
Jednak należy pamiętać o pozostałych poradach z tego rozdziału. Komentarze Javadoc mogą być
równie mylące, nie na miejscu i nieszczere jak wszystkie inne komentarze

Tobie się przyda czytanie zrozumieniem. Czy ja Ci daje rady pisz sobie jak chcesz, możesz komentarzy nie dawać, nikt Ci tego nie zabroni. Wyjaśniłem Ci tylko czemu tego się używa, to że zaciemnia kod to ja wcale nie twierdze że tak nie jest. Ale dlatego też w łatwy sposób można je z pliku usunąć

Kolejny co odbiera wszystko personalnie i ma ból tyłka potem, daruj sobie

Poza tym nawet nie zrozumiałeś tego co napisał Pyton_000, który wyraźnie napisał:

@NickOver miał na myśli komentowanie kodu samego w sobie, nie komentarze dla funkcji czy klasy bo to oczywiście obowiązkowe.

[Dejmien_85]

Skoro przeczytałeś czysty kod chwała Ci za to ale skoro już o tym mowa:

Przeczytałem i cieszy mnie to, że Ty też się w tym orientujesz, choć jak widać się nie stosujesz - ten tekst o publicznym API także pamiętam. Jest to jednak jedyny przypadek, kiedy dokumentacja *może* zostać użyta rozsądnie.

Nie wykluczam tej opcji, pragnę tylko podkreślić fakt, że pisanie dokumentacji "na mus" jest niczym więcej jak generowaniem masy zbędnego i rozpraszającego tekstu. Tak, komentarze są szare (z natury), można nawet przy pomocy IDE zmienić kolor na inny, ale to nie zmienia faktu, że komentarze są w większości przypadków po prostu kompletnie zbędne i nastawienie "there shall be comments!" prowadzi do chaosu.

Dobra, wystarczy na dzisiaj tych kazań, idziem spać!

Szerokości.

[com]

Ale phpdoca generuje się do opisu API przecież, a nie dla siebie żeby zaśmiecać sobie tym kod. Komentarze w normalnych IDE można zwijać i to tez nie problem. Poza tym jak już mówiłem można je łatwo usunąć. Jeśli z kodu korzystać ma ktoś inny to znacznie prościej jest mu przejrzeć coś takiego dajmy przykład SF2
http://api.symfony.com/2.0/Symfony/Compone...on/Request.html
Niż analizować coś takiego
https://github.com/symfony/symfony/blob/2.7...ion/Request.php
Gdzie dostaje 1984 linie kodu.
To że Ty będziesz pisał ładnie, nie znaczy, że jak dostaniesz czyjś kod to będzie tak samo. Jasne, że znacznie prościej jest jak nie ma ich wcale, ale mało osób trzyma sie w php jakichkolwiek zasad. Są standardy typu PSR a większość tu obecnych nigdy o nich nie słyszała itd. Więc o wiele prościej jest wygenerować sobie takiego phpdoca, niż przegladać lina po lini np te 1984 wiersze żeby poznać jego budowę, a potem jeszcze użyć

Ale ja wcale nie powiedziałem nic takiego jak Ty mówisz, sam sobie dopowiedziałeś. Kiedy pisze coś wewnętrznego i zamkniętego to wcale komentarzy bym nie potrzebował, one generowane są dla wygody pracy z IDE, ale nie problem je po zakończeniu dev usunąć.

Niemniej jednak rozumiem o co Ci w głównej mierze chodziło

Tylko z drugiej strony to ze cos jest dobre dla wiekszej ilosci przypadkow i sprawdzi sie w cpp,c#,javie itd to nie znaczy ze tamo bedzie w przypadku jezyka skryptowego. Narazie puki nie mamy wersji 7 nie ma silnego typowania. Mozliwosci na tym poziomie sa bardzo ograniczone wiec taki phpdoc ulatwia Ci zadanie bo widzisz co masz przekazac i co zwroci Ci dana metoda. Inaczej jest w jezykach wysokiego poziomu gdzie masz typowanie i bez problemu z samej deklaracji da sie wszystko wyczytac zagladajac np w cpp do samego naglowka. I tam sie to faktycznie sprawdza ale niestety nie tu.


Kolejna sprawa komentarze to nie tylko phpdoc. Masz tez adnotacje jak chociazby w sf dla routingu i template czy tez doctrine

Ten post edytował com 26.03.2015, 01:36:09

[NickOver]

Od zawsze
@NickOver miał na myśli komentowanie kodu samego w sobie, nie komentarze dla funkcji czy klasy bo to oczywiście obowiązkowe.

Komentowanie kodu to tylko ukrycie fatalnie napisanego kodu. Skoro ktoś pisze komentarz to znaczy że kod który napisał jest nieczytelny i nie da się wywnioskować w 2s. co on robi.
Dodatkowo komentarze się przedawniają. Mało kto dba o ich aktualizację podczas zmiany kodu.
Dlatego trzeba pisać kod jasny i czytelny aby na podstawie nazwy metody wiedzieć co ona robi bez zagłębiania się w kod. Jesli tak nie jest - jest fatalnie.

Również czytałeś czysty kod?

@topic
Tak jak Python napisał nie chodziło mi o komentarze takie hmmm... Generalne lecz o komentarze typu ta metoda w tej linijce robi to i to. Jeśli musisz to pisać to kod jest napisany źle ponieważ nawet jeśli masz kod który już napisany nie będzie edytowany to i tak robi się problem jeśli osoba która go czyta nie zna języka w którym jest napisany.
@up @up1 @up2 i chyba @up3
Nie sądzicie że ten temat, dizał i całe forum nie jest najlepszym miejscem na obrzucanie się docinkami kto umie więcej a kto mniej?

[com]

NickOver A czy jak kogoś obrzucałem docinkami? Dejmien_85 wystartował do mnie bo odebrał personalnie to co napisałem, a ja tylko wytłumaczyłem mu merytorycznie poco to jest i wcale nie reagowałem na jego osobiste zaczepki, wiec luz chłopie, nie ma co do tego wracać