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)