🚀 go-pugleaf

> > 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/rezystory-smd-0805/vishay/

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

https://www.tme.eu/Document/622e28308c06d160637f2b14751ba16b/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