> "Documentation is any communicable material that is used to describe, explain or
instruct regarding some attributes of an object, system or procedure, such as its
parts, assembly, installation, maintenance and use"
>
> Kod źródłowy jest komunikowalny i może być użyty do wyjaśnienia pewnych atrybutów
systemu, więc nadal nie rozumiem.

To jest pomysł tej samej warstwy społecznej, która wymyśliła "Working software over
comprehensive documentation" i ogólnie tej grupy, która systematycznie nie jest w
stanie zrobić sensownej dokumentacji, więc kombinuje jak by tu uzasadnić drobny fakt,
że jej po prostu nie ma.

Kod źródłowy oczywiście, że może być komunikowalny. Ale nie jest w stanie wyjaśnić
"dlaczego" ani "w jakim celu", czyli nie jest w stanie niczego uzasadnić. Właśnie do
tego jest dokumentacja. Oczywiście można zrobić tak:

int maxNumberOfBananasThatTheCustomerXYZAskedForAtTheLas
tMeeting = 12345;

ale chyba rozumiemy, że taka nazwa to nie jest kod, tylko niewłaściwie użyty
komentarz. Czyli dokumentacja. I się pewnie zaraz rozjedzie.
Można też tak:

int maxNumberOfBananas = 12345;

ale bez (rozjeżdżającej się) dokumentacji nie wiemy, dlaczego akurat tyle. A to może
być bardzo ważne.
Zrobienie tego samego (w obu wersjach) na diagramie, który posłuży do automatycznego
wygenerowania takiego kodu niczego nie zmienia, tylko przenosi problem w inne miejsce
w procesie produkcyjnym.

Kod programu nie jest dokumentacją. Diagram może być ilustracją w dokumentacji, ale
jeśli diagram służy do generowania kodu, to nie jest. Taki diagram nadal wymaga
dokumentacji.

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

do góry

sobota, 27 marca 2021 o 17:08:22 UTC+1 Maciej Sobczak napisał(a):
> > "Documentation is any communicable material that is used to describe, explain or
instruct regarding some attributes of an object, system or procedure, such as its
parts, assembly, installation, maintenance and use"
> >
> > Kod źródłowy jest komunikowalny i może być użyty do wyjaśnienia pewnych atrybutów
systemu, więc nadal nie rozumiem.
> To jest pomysł tej samej warstwy społecznej, która wymyśliła "Working software over
comprehensive documentation" i ogólnie tej grupy, która systematycznie nie jest w
stanie zrobić sensownej dokumentacji, więc kombinuje jak by tu uzasadnić drobny fakt,
że jej po prostu nie ma.
>
> Kod źródłowy oczywiście, że może być komunikowalny. Ale nie jest w stanie wyjaśnić
"dlaczego" ani "w jakim celu", czyli nie jest w stanie niczego uzasadnić. Właśnie do
tego jest dokumentacja. Oczywiście można zrobić tak:
>
> int maxNumberOfBananasThatTheCustomerXYZAskedForAtTheLas
tMeeting = 12345;
>
> ale chyba rozumiemy, że taka nazwa to nie jest kod, tylko niewłaściwie użyty
komentarz. Czyli dokumentacja. I się pewnie zaraz rozjedzie.
> Można też tak:
>
> int maxNumberOfBananas = 12345;
>
> ale bez (rozjeżdżającej się) dokumentacji nie wiemy, dlaczego akurat tyle. A to
może być bardzo ważne.
> Zrobienie tego samego (w obu wersjach) na diagramie, który posłuży do
automatycznego wygenerowania takiego kodu niczego nie zmienia, tylko przenosi problem
w inne miejsce w procesie produkcyjnym.
>
> Kod programu nie jest dokumentacją. Diagram może być ilustracją w dokumentacji, ale
jeśli diagram służy do generowania kodu, to nie jest. Taki diagram nadal wymaga
dokumentacji.

Nadal nie wyjaśniłeś dlaczego nie jest.
Najpierw jak zapytałem, to wkleiłeś link do artykułu na Wikipedii, który twierdzi, że
dokumentacją jest wszystko, co służy do wyjaśnienia działania jakiegoś systemu.
Teraz drugi raz twierdzisz, że jeżeli diagram posłuży do wygenerowania kodu, to nagle
w jakiś magiczny sposób przestaje być dokumentacją (co w świetle definicji z
Wikipedii oznaczałoby, że nie może już służyć do rozumienia działania systemu, bo
wówczas... byłby dokumentacją).

Z tego co widzę, swoje uzasadnienie opierasz na ad hominem względem jakiejś grupy
ludzi, która kiedyś coś twierdziła, oraz na tym, że kod źródłowy nie dokumentuje
wszystkich aspektów budowy i użytkowania systemów. No to teraz uważaj:
żadna dokumentacja nie dokumentuje wszystkich aspektów budowy i użytkowania systemów.

W szczególności, można znaleźć dużo dokumentacji, która również nie wyjaśnia,
dlaczego albo w jakim celu danego komponentu systemowego można użyć. Weźmy pierwszy z
brzegu przykład - podręcznik do funkcji "memcpy"

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.

Nie zmienia to jednak faktu, że ta strona manuala jest dokumentacją. (Chyba że zaraz
stwierdzisz, że nie jest)

Twój przykład z "niewłaściwie użytym komentarzem" może też pokazuje gdzie może leżeć
źrodło nieporozumienia.
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.

do góry

> 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

do góry

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

do góry

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

Dlatego próbuję pomóc.

> No, ale już kliknięcie dalej mamy artykuł
https://en.wikipedia.org/wiki/Software_documentation
,

... w którym w pierwszym zdaniu jest "that accompanies computer software", czyli
znowu jest intencja rozdzielenia obiektu od jego dokumentacji, tudzież "or is
embedded in the source code" jako logistyczny wybór miejsca umieszczenia, co nadal
jednak odróżnia dokumentację od kodu źródłowego.

> w którym jest m.in. omówiona koncepcja programowania piśmiennego Knutha.

Wiadomo, że "Knuth wielkim poetą był", ale po pierwsze nadal ta koncepcja odróżnia
obiekt od jego dokumentacji, a po drugie ta koncepcja nie przyjęła się w sensownej
skali pomimo prawie 4 dekad od ogłoszenia (1984). Więc nie.

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

Tak. Ponieważ nie tylko tak uważam, ale nawet przypadkiem zgadza się to z Wikipedią,
którą wolę wtedy pokazać jako bardziej neutralne źródło.

> Mnie się zdarza studiować asembler, dokładnie w tym celu, żeby zrozumieć, co robi
system

A co, nie było dokumentacji? :-D
To się wtedy nazywa reverse-engineering. Ale to nie znaczy, że asembler jest
dokumentacją. To znaczy tylko tyle, że nie było dokumentacji.

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

Hm... Bo nie jest dokumentacją?

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

Sam podałeś link. Tam, gdzie w pierwszym zdaniu jest "that accompanies computer
software".
"Accompanies" oznacza, że jest obok.

> Proszę, tu piosenka dla Ciebie

To miłe, ale nie szukam tu muzyki.

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

do góry

wtorek, 30 marca 2021 o 23:00:20 UTC+2 Maciej Sobczak napisał(a):

> > No, ale już kliknięcie dalej mamy artykuł
https://en.wikipedia.org/wiki/Software_documentation
,
> ... w którym w pierwszym zdaniu jest "that accompanies computer software", czyli
znowu jest intencja rozdzielenia obiektu od jego dokumentacji, tudzież "or is
embedded in the source code" jako logistyczny wybór miejsca umieszczenia, co nadal
jednak odróżnia dokumentację od kodu źródłowego.

Podejrzewam, że "is embedded in the source code" można rozumieć różnie --
niekoniecznie jako odróżnienie.
Skrzynia biegów albo silnik też jest "embedded" w samochód, i raczej byśmy
powiedzieli, że skrzynia biegów "jest częścią" samochodu, niż czymś "odróżnionym od
samochodu"

> > w którym jest m.in. omówiona koncepcja programowania piśmiennego Knutha.
> Wiadomo, że "Knuth wielkim poetą był", ale po pierwsze nadal ta koncepcja odróżnia
obiekt od jego dokumentacji, a po drugie ta koncepcja nie przyjęła się w sensownej
skali pomimo prawie 4 dekad od ogłoszenia (1984). Więc nie.

Ale więc "co" "nie"?
Jest omówiona, czyli jest omówiona.
W artykule dotyczącym dokumentacji oprogramowania.
Więc tak.

> > 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ż ..."
> Tak. Ponieważ nie tylko tak uważam, ale nawet przypadkiem zgadza się to z
Wikipedią, którą wolę wtedy pokazać jako bardziej neutralne źródło.

Tzn. raczej zgadza się z "Twoim odczuwaniem Wikipedii", niż z czymkolwiek, co tam
jest napisane.

> > Mnie się zdarza studiować asembler, dokładnie w tym celu, żeby zrozumieć, co robi
system
> A co, nie było dokumentacji? :-D

Mam jeszcze raz zacytować definicję spod linku, który wkleiłeś? OK:

"any communicable material that is used to describe, explain or instruct regarding
some attributes of an object, system or procedure, such as its parts, assembly,
installation, maintenance and use"

Zobacz, "assembly" jest nawet wymienione explicite ;]

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.
> Sam podałeś link. Tam, gdzie w pierwszym zdaniu jest "that accompanies computer
software".
> "Accompanies" oznacza, że jest obok.

"or embedded in"

"embedded in" oznacza, że jest w środku.

do góry

> Dokumentacja może zawierać kod źródłowy

Oczywiście. Nikt nie twierdził inaczej. Trzymanie dwóch rzeczy w jednym pojemniku to
decyzja logistyczna. Czasem dobra, czasem niedobra.

> Kod źródłowy może zawierać
> dokumentację

Oczywiście. Nikt nie twierdził inaczej. Trzymanie dwóch rzeczy w jednym pojemniku to
decyzja logistyczna. Czasem dobra, czasem niedobra.

> Kod źródłowy może być
> samokomentujący,

Na tej samej zasadzie co deska o długości 1.2m jest samokomentująca, bo przecież
widać, że ma 1.2m.

> a komentarze to też dokumentacja

Oczywiście. Nikt nie twierdził inaczej. Ale o tym, że kod może zawierać dokumentację,
było już parę linijek wyżej.

> Czyli w konkretnych przypadkach dokumentacja to kod źródłowy i
> vice versa.

A to zdanie nie wynika z żadnego z tych powyżej. I chyba na tym skrócie myślowym nam
się wcześniej dyskusja urwała. Bo ja nadal odróżniam te dwie rzeczy.

> Przy tym zupełnie mało interesująca są: statystyka; wierzenia
> korpoludków; Wikipedia (Oxenfurt i Sorbowit ubogich).

Niech będzie. To co teraz? :-D

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

do góry

poniedziałek, 5 kwietnia 2021 o 19:10:47 UTC+2 Maciej Sobczak napisał(a):

> > Kod źródłowy może być
> > samokomentujący,
> Na tej samej zasadzie co deska o długości 1.2m jest samokomentująca, bo przecież
widać, że ma 1.2m.

O, wyśmienity przykład.
Jeżeli masz system oznaczania desek (np. naklejasz albo wypalasz oznaczenie na
elemencie), i zaprojektujesz oznaczenia w ten sposób, że masz deskę typu A, deskę
typu B, itd., to będziesz potrzebował dodatkowej dokumentacji, żeby sobie
przetłumaczyć "typ" deski na jej wymiar. Natomiast jeżeli zamiast "A" napiszesz na
desce "120x15x2", i deska będzie miała wymiary 120cm x 15cm x 2cm, to nie będziesz
potrzebował tej dodatkowej dokumentacji.

W programowaniu jest podobnie, tylko że bardziej. Wcześniej pisałeś tak:

> Oczywiście można zrobić tak:
>
> int maxNumberOfBananasThatTheCustomerXYZAskedForAtTheLas
tMeeting = 12345;
>
> ale chyba rozumiemy, że taka nazwa to nie jest kod, tylko niewłaściwie użyty
komentarz. Czyli dokumentacja. I się pewnie zaraz rozjedzie.
> Można też tak:
>
> int maxNumberOfBananas = 12345;
>
> ale bez (rozjeżdżającej się) dokumentacji nie wiemy, dlaczego akurat tyle. A to
może być bardzo ważne.

Teraz zwróć uwagę, że zamiast "maxNumberOfBananas" mogłeś użyć np. nazwy "x" albo
"mnb". Ale tego nie zrobiłeś, bo "x" ani "mnb" nie wyjaśniałoby roli rzeczonej
zmiennej (którą jest -- jak bym chciał wierzyć -- maksymalna liczba bananów w jakimś
kontekście) wymagałaby dodatkowego źródła. Dlatego też nazwa zmiennej (będąca
częścią kodu źródłowego, a nie tylko logistycznie współwystępującym elementem w
kodzie źródłowym -- i oczywiście o ile jest poprawnie użyta) dokumentuje rolę tej
zmiennej w systemie.

Rzecz jasna jest tak, że kod źródłowy może dokumentować zachowanie systemu lepiej
albo gorzej (podobnie jak każda inna dokumentacja może być napisana lepiej albo
gorzej), ale stąd nie wynika, że -- jak uparcie twierdzisz (mimo że nie wskazują na
to ŻADNE materiały źródłowe, na które dotychczas próbowałeś się powoływać) -- przez
sam fakt swojej potencjalnej wykonywalności (bądź bycia przetwarzalnym do jakiejś
postaci wykonywalnej) -- nie może być dokumentacją.

Wydaje mi się też, że Twoja teoria miałaby problem z wyjaśnieniem istnienia tego
artykułu na osławionej Wikipedii:

https://en.wikipedia.org/wiki/Self-documenting_code

Nota bene, swego czasu popełniłem na Wikipedii artykuł, który pokazywał, jak przejść
od kodu, który dokumentuje siebie w komentarzach, do takiego, który jest
samo-dokumentujący:

https://www.quora.com/What-are-some-examples-of-bad-
code/answer/Panicz-Godek

Oczywiście nie jest tak, że sprawa nie jest w jakimś stopniu osobliwa: jak wpiszesz w
wyszukiwarkę "self-documenting", to główną podpowiedzią (przynajmniej u mnie) jest
właśnie "code", i wygląda na to, że -- poza kodem źródłowym -- niewiele jest innych
artefaktów, które mogłyby mieć potencjał "dokumentowania siebie samych" (choć np. w
wielu książkach widziałem sekcję pt. "jak używać tej książki", którą poniekąd można
postrzegać jako dokumentację książki do niej samej)

do góry

> Nota bene, swego czasu popełniłem na Wikipedii artykuł, który pokazywał, jak
przejść od kodu, który dokumentuje siebie w komentarzach, do takiego, który jest
samo-dokumentujący:
>
> https://www.quora.com/What-are-some-examples-of-bad-
code/answer/Panicz-Godek

Errata: miało być oczywiście "na Quorze", a nie "na Wikipedii".
(Na Wikipedii nie popełniłem nigdy żadnego)

do góry

> > Na tej samej zasadzie co deska o długości 1.2m jest samokomentująca, bo przecież
widać, że ma 1.2m.
> O, wyśmienity przykład.
> Jeżeli masz system oznaczania desek (np. naklejasz albo wypalasz oznaczenie na
elemencie), i zaprojektujesz oznaczenia w ten sposób, że masz deskę typu A, deskę
typu B, itd., to będziesz potrzebował dodatkowej dokumentacji, żeby sobie
przetłumaczyć "typ" deski na jej wymiar. Natomiast jeżeli zamiast "A" napiszesz na
desce "120x15x2", i deska będzie miała wymiary 120cm x 15cm x 2cm, to nie będziesz
potrzebował tej dodatkowej dokumentacji.

Nadal jednak deska nie jest dokumentacją.
Nawet pomimo faktu, że patrząc na deskę odpowiednio długo, można się o niej czegoś
dowiedzieć.

> W programowaniu jest podobnie, tylko że bardziej.

Bo medium może być współdzielone. Nadal jednak odróżniam te dwie rzeczy.

> Teraz zwróć uwagę, że zamiast "maxNumberOfBananas" mogłeś użyć np. nazwy "x" albo
"mnb".

Mogłem. Ale w większym programie kończą mi się literki. No i mogłem też na desce
napisać "deska". Albo nawet "DESKA".
Pomimo ułatwienia sobie życia przez staranne nazewnictwo, nadal nie ma tam
dokumentacji.

> Rzecz jasna jest tak, że kod źródłowy może dokumentować zachowanie systemu lepiej
albo gorzej

Kod nie dokumentuje działania, tylko go definiuje. Jest specyfikacją dla generatora
kodu, już pisałem o tym.
Można do czegoś takiego dopisać dokumentację. Ale w wielu przypadkach się tego nie
robi, bo w naszej dziedzinie reverse engineering też jest powszechnie akceptowalną
metodą poznawczą.

> Wydaje mi się też, że Twoja teoria miałaby problem z wyjaśnieniem istnienia tego
artykułu na osławionej Wikipedii:
>
> https://en.wikipedia.org/wiki/Self-documenting_code

Ja w ogóle nie podejmuję się wyjaśniania istnienia czegokolwiek.
Również tego:

https://en.wikipedia.org/wiki/Self-documenting_code#
Criticism

Self-documenting code to taka ładna nazwa na brak dokumentacji. Zdecydowanie lepiej
jest powiedzieć na standupie, że się napisało self-documenting code (positive
thinker, constructive attitude, involvement, engagement, etc.), niż że się nie
napisało dokumentacji.
Ale jak już pisałem, reverse-engineering jest akceptowalną metodą poznawczą, więc w
czym problem?

> Oczywiście nie jest tak, że sprawa nie jest w jakimś stopniu osobliwa: jak wpiszesz
w wyszukiwarkę "self-documenting", to główną podpowiedzią (przynajmniej u mnie) jest
właśnie "code", i wygląda na to, że -- poza kodem źródłowym -- niewiele jest innych
artefaktów, które mogłyby mieć potencjał "dokumentowania siebie samych"

Słuszne spotrzeżenie, ale wyjaśnienie tego jest bardzo proste. Otóż wbrew temu, co
my, jako programiści, lubimy o sobie myśleć, to nasza branża jest właśnie jedną z
najbardziej dziadowskich jeśli chodzi o akceptację niskiej kultury pracy. Dlatego w
innych branżach inżynierskich nie spotkasz czegoś takiego jak samo-dokumentujący się
artefakt, bo z punktu widzenia każdego dojrzałego procesu produkcyjnego albo systemu
kontroli jakości, jest to po prostu przypadkowy śmieć.
Spróbuj popatrzeć na branżę elektroniczną, jako tą powiedzmy najbliższą technicznie
naszej (w systemach embedded z płynną granicą pomiędy nimi), i weź coś najprostszego,
tak naprawdę na samym dole drabinki społecznej, czyli no nie wiem, np. najbardziej
banalny rezystor 100Ohm, 1%, taki co to kosztuje poniżej jednego grosza za sztukę,
np:

https://www.tme.eu/pl/details/crcw0805100rfktabc/rez
ystory-smd-0805/vishay/

A tak wygląda dokumentacja do tego najprostszego na świecie produktu:

https://www.tme.eu/Document/622e28308c06d160637f2b14
751ba16b/Data%20Sheet%20CRCW_BCe3.pdf

Rozumiesz już?
My jesteśmy w lesie.

To co my robimy w naszej pracy to nie jest dokumentacja, tylko kpiny. I właśnie to
próbuję nieśmiało tu zasygnalizować.
Oczywiście, możemy sobie dalej tkwić w wirtualnym świecie poklepujących się nawzajem
po ramieniu amatorów tworzących "self-documenting code". Czy co tam. Ale możemy też
pokusić się o refleksję.

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

do góry