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?