> 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.

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.

> 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ść.
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ą.
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ą.

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.

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.

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.

> 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.

> 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.

> 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?

Serio, dokumentację robi się gdzie indziej.

--
Maciej Sobczak * http://www.inspirel.com