poniedziałek, 29 marca 2021 o 18:39:49 UTC+2 Maciej Sobczak napisał(a):
> > Nadal nie wyjaśniłeś dlaczego nie jest.
> Myślałem, że wystarczy praca samodzielna.
> Ideą, ktorą ja wyczuwam w tym artykule, jest odróżnienie dokumentacji od
dokumentowanego obiektu. Wynika to nawet bezpośrednio z podanych tam przykładów.

Niestety, ja nie jestem w stanie tego nigdzie wyczytać, a moje moce do wyczuwania są
najwidoczniej zbyt słabe

> A najbardziej wynika z paragrafu o dokumentacji w naszej branży:
>
> https://en.wikipedia.org/wiki/Documentation#Document
ation_in_computer_science
>
> Kod źródłowy nie znajduje się na tej liście.

Aha, czyli chodzi nie o to, co jest, ale o to, czego nie ma.
No, ale już kliknięcie dalej mamy artykuł
https://en.wikipedia.org/wiki/Software_documentation
, w którym jest m.in. omówiona koncepcja programowania piśmiennego Knutha.

> > Teraz drugi raz twierdzisz, że jeżeli diagram posłuży do wygenerowania kodu, to
nagle w jakiś magiczny sposób przestaje być dokumentacją
> Tak. Subtelne, prawda? To trochę kwestia kultury pracy i jest to miejsce na
subiektywność.

OK, to zamiast mówić "wykonywalny diagram nie jest dokumentacją", a później
uzasadniać to linkiem do Wikipedii, z którego to nie wynika, możesz powiedzieć "ja
wykonywalnego diagramu nie uważam za dokumentację, ponieważ ..."

> Ja to widzę tak, że jeżeli coś jest bezpośrednio na ścieżce albo w łańcuchu
transformacji artefaktów inżynierskich, to jest obiektem wymagającym dokumentacji a
nie dokumentacją.

Jedno drugiego nie wyklucza.
Co więcej, do dokumentacji też można tworzyć dokumentację.
I nie ma w tym nic strasznego.

> Zauważ (znowu, bo już o tym wspomniałem), że kod źródłowy to nie jest program, choć
zawsze tak skrótowo o nim myślimy i mówimy. Kod źródłowy to jedynie konfiguracja dla
generatora kodu dla niższej wartwy abstrakcji. I to nadal nie musi być program, bo
jeśli kompilator generuje kod w asemblerze, to dalej z tego jest generowany kod
obiektowy i to nadal nie jest program, bo trzeba to zlinkować i pozszywać symbole i
to może dopiero jest program, który zostanie fizycznie wykonany przez komputer. Tak,
w skrócie mówimy, że "napisałem program", ale to nie jest prawda, bo program dopiero
powstanie. Później.
> I jeżeli teraz chciałbyś w ten długi łańcuch kolejnych generacji z jednego w drugie
dołożyć jeszcze jeden etap, np. model (w postaci diagramu), z którego zostanie
wygenerowany kod źródłowy, z którego... itd., to coś się zmieniło w całej logice? Nic
się nie zmieniło. I możesz dalej sobie coś dołożyć, np. meta-skrypt generujący takie
modele z zadanej konfiguracji. I coś to zmienia? Dalej nic.
> Bo na całym tym łańcuchu masz artefakty inżynierskie, które automatyzują proces
powstania produktu końcowego. I *żaden* z tych artefaktów nie jest wtedy
dokumentacją.

Jeżeli zapoznanie się z którymkolwiek powodowałoby zwiększenie zrozumienia działania
systemu, to wówczas byłby dokumentacją.
Tak przynajmniej twierdzi Wikipedia. Bo ona mówi, że jest to "dowolny materiał,
który..."

> Bo gdyby był, to każdy z nich też by był. Ten asembler też. A to by było słabe,
prawda? W tym sensie, że słowo "dokumentacja" straciłoby swój pierwotny sens.

Tak, potencjalnie każdy jest dokumentacją, bo każdy zawiera informację, którą można
przyswoić.
Mnie się zdarza studiować asembler, dokładnie w tym celu, żeby zrozumieć, co robi
system (wtedy, kiedy to jest istotne).

Jedyna kwestia jest taka, że nie każdy artefakt w tym procesie jest zoptymalizowany
do rozumienia działania systemu na poziomie użytkowym.

> Więc subtelne rozróżnienie jest właśnie w tym, czy coś jest na ścieżce
automatycznej generacji ostatecznego produktu. Jeśli jest, to nie jest to
dukumentacja, bo ta jest z definicji obok tej ścieżki.

Nic takiego nie znalazłem na Wikipedii.

> Tak, wiem, że są ludzie, dla których kod źródłowy jest jednocześnie programem i
dokumentacją. I dziełem sztuki. Bo przecież powstało dzieło.

OK, są ludzie, dla których jest, i są ludzie, dla których nie jest. To jest w
porządku.
Są też ludzie, którzy twierdzą, że to, co oni uważają w tej kwestii, jest ostateczną
prawdą, a to co uważają inni, to jakieś bzdury. I to jest mniej w porządku.

> > co w świetle definicji z Wikipedii oznaczałoby, że nie może już służyć do
rozumienia działania systemu
> No bo nie może. To, że coś pokazuje *jak* coś działa, nie znaczy, że pokazuje
*dlaczego*. A to jest potrzebne do rozumienia.

*Dlaczego* jest potrzebne do zrozumienia dlaczego coś zostało zrobione. *Jak* jest
potrzebne do zrozumienia, jak coś jest zrobione.
W obu przypadkach mamy do czynienia ze zrozumieniem.

> > No to teraz uważaj:
> > żadna dokumentacja nie dokumentuje wszystkich aspektów budowy i użytkowania
systemów.
> Bo nie musi. Natomiast kod źródłowy w ogóle niczego nie dokumentuje.
> > https://man7.org/linux/man-pages/man3/memcpy.3.html
> >
> > Opisuje różne aspekty użycia funkcji `memcpy`, ale nie wyjaśnia, dlaczego ta
funkcja powstała, ani w jakim celu się ją stosuje.
> Bardzo dobrze opisuje. Nawet warunki poprawnego użycia są opisane. Dobry kawał
dokumentacji.
> A że jest to funkcja bardzo niskopoziomowa, to nie dowiesz się z tej dokumentacji,
w jakim celu się ją stosuje.

Innymi słowy, dowiem się *jak* tego użyć, ale nie dowiem się *dlaczego* tego użyć.
(A teraz przeczytaj to, co napisałeś akapit wyżej)

> > Bo nie wiem jak Ty, ale ja swoje komentarze do kodu źródłowego zazwyczaj trzymam
w kodzie źródłowym.
> > One *są częścią* kodu źródłowego, i wyjaśniają rzeczy, których w samym języku
programowania nie mógłbym wyrazić, albo tłumaczą, skąd się wzięły jakieś nieoczywiste
rozwiązania.
> No, to już jesteś powyżej średniej. Obiektywnie, bez żartów.
> Ale twierdzenie, że komentarze są częścią kodu źródłowego, to miejsce do nadużyć.
Bo fakt, że komentarze są z definicji ignorowane i drugi fakt, że ich związek z
otoczeniem jest jedynie umową społeczną między autorem a czytelnikiem, sprawia, że
jednak nie są częścią kodu. Umieszczenie różnych rzeczy w tym samym pliku to jedynie
fizyczny wybór pojemnika, który to wybór nie wpływa na to, czym coś jest.
> I zapewniam, że niektórzy piszą komentarze do kodu poza kodem. Robiłeś kiedyś
review kodu w jakimś narzędziu do pracy zespołowej?

Tak, zdarza mi się. I tego rodzaju komentarzy nie uznaję za część kodu źródłowego,
tylko za element konwersacji wokół kodu źródłowego.

Tak samo, jak np. narzędzie do pisania komentarzy w Wordzie odróżnia komentarz od
komentowanego tekstu.

> Serio, dokumentację robi się gdzie indziej.

Zależy jaką. Serio. Wiele rzeczy można robić na wiele sposobów.

Proszę, tu piosenka dla Ciebie (moim zdaniem powinna być hymnem inżynierów):

https://www.youtube.com/watch?v=6DiwN1LHfOU