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

[Pyton_000]

Od zawsze (IMG:style_emoticons/default/wink.gif)
@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.

[Dejmien_85]

Od zawsze (IMG:style_emoticons/default/wink.gif)
@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