🚀 go-pugleaf

poniedziałek, 12 kwietnia 2021 o 17:58:26 UTC+2 Maciej Sobczak napisał(a):
> > > Ale to nie odpowiada na pytanie, po co napisał książkę. Kod by napisał, taki samokomentujący, i by stykło. Nie? 
> > Równie dobrze mógłbyś pytać, dlaczego nauczyciele prowadzą z uczniami lekcje czytania.
> Zgadzam się, że na logiczną dyskusję chyba nie ma już szans...

Szanse są zawsze. Tylko to wymaga przede wszystkim wysiłku zdefiniowania używanych w dyskusji terminów, i trzymania się tych definicji. Wierzę, że stać Cię na taki wysiłek.

> > Błąd, jaki Ty popełniasz, polega na tym, że ze stwierdzenia, że coś jest dokumentacją, próbujesz wyciągać wniosek, że owo coś jest wyczerpującą albo jedyną potrzebną dokumentacją.
> Bo właśnie tak to działa w powszechnym odbiorze. W sensie - ktoś, kto nie napisał dokumentacji stwierdza, że przecież jego kod jest tak bardzo samodokumentujący, że już niczego więcej nie trzeba. I tak to zostaje. 

Jak to mówią, "ogólnie różnie bywa".
Jeżeli rzeczywiście niczego więcej nie potrzeba, to czas, który nie został wydatkowany na robienie dokumentacji, to czas zaoszczędzony.
A jeżeli potrzeba czegoś więcej, to ta potrzeba prędzej czy później da o sobie znać w jakimś procesie.
Pisanie dokumentacji po to, żeby była napisana dokumentacja, to kiepski pomysł.

Znów mogę posłużyć się przykładem. Ostatnio zajmowałem się trochę kwestią parsowania z zachowaniem komentarzy i białych znaków. Napisałem parser i podzieliłem się nim ze swoim przyjacielem, z którym często sobie rozmawiamy na różne tematy:

https://github.com/panicz/grasp-android/blob/master/javor/parse.scm

w odpowiedzi przyjaciel napisał swoją wersję parsera, którą podzielił się ze mną:

https://github.com/drcz/random-crap/blob/master/pod-jaworem.scm

Ponieważ "mówimy wspólnym językiem", i obaj wyrobiliśmy w sobie nawyk pisania przykładów w kodzie źródłowym, żadna dodatkowa dokumentacja nie była potrzebna. Nic by nie wniosła.

> Więc warto jednak dbać o rozróżnianie pojęć, w przeciwnym razie pogubimy się w ich rozmyciach. 

Przede wszystkim należy zacząć od zdefiniowania pojęć.

> Więc zadbajmy o takie rozróżnienie: kod *nie* jest dokumentacją. Może sobie być poezją w jakimś pozainżynierskim kontekście (no chyba że poeci zgłoszą jakiś sprzeciw, np. poczują się obrażeni albo coś), ale nie jest dokumentacją.

Według JAKIEJ definicji "dokumentacji"?

> > Samodokumentujący kod zawiera wszystko, co jest potrzebne do tego, żeby zrozumieć, jak jakiś system działa.
> "Koń jaki jest, każdy widzi." Wiesz, skąd to zdanie pochodzi? Z bardzo poważnego źródła. Ale jednak z biegiem czasu zaczęliśmy wymagać więcej, więc nawet w tych poważnych źródłach już takich zdań nie ma. 

Nie rozumiem.

> > Nie zawiera za to, na przykład, informacji [...] 
> 
> Bo nie jest dokumentacją.

Według JAKIEJ definicji?

> > Książka Martina jest (kiepskim bo kiepskim, ale jednak) materiałem, który ma trenować tę umiejętność.
> Umiejętność czego?

Pisania kodu, do którego zrozumienia nie potrzeba dodatkowej dokumentacji.

> Nadal jednak kod nie jest dokumentacją.

Według JAKIEJ definicji?