🚀 go-pugleaf

> 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#Documentation_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