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