wtorek, 6 kwietnia 2021 o 18:35:44 UTC+2 Maciej Sobczak napisał(a):
> > > 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ć.

To, czy deska jest, czy nie jest dokumentacją, zależy - według podanej przez Ciebie
definicji - od tego, czy służy do "wyjaśnienia, opisania bądź poinstruowania odnośnie
pewnych atrybutów jakiegoś przedmiotu, systemu lub procedury, takich jak jego części,
sposób budowy, montażu, obsługi czy też użytkowania".
Jeżeli służy do któregoś z tych celów, to jest dokumentacją, a jeżeli nie służy, to
nie jest.
(Akurat w przypadku deski jestem bez trudu w stanie sobie wyobrazić, że może być
częścią dokumentacji jako referencyjna jednostka długości w jakimś projekcie)

> > W programowaniu jest podobnie, tylko że bardziej.
> Bo medium może być współdzielone. Nadal jednak odróżniam te dwie rzeczy.

W porządku. Ty odróżniasz. Ale Wikipedia, na którą się powołujesz, nie odróżnia.

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

Jeżeli napis "DESKA" na desce może posłużyć do wyjaśnienia, opisania bądź
poinstruowania odnośnie pewnych atrybutów jakiegoś przedmiotu, systemu lub procedury,
takich jak jego części, sposób budowy, montażu, obsługi czy też użytkowania, to
wówczas jest tam dokumentacja.

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

Nie rozumiem w jaki sposób jedno miałoby wykluczac drugie.
Definiuje, to znaczy: nie dość, że dokumentuje, to jeszcze dokumentuje w sposób
źródłowy czy też rozstrzygający.

> Można do czegoś takiego dopisać dokumentację.

Do wszystkiego można dopisać dokumentację. Ale nie wynika stąd, że to, do czego
dopisujemy dokumentację, samo nie jest dokumentacją.

> Ale w wielu przypadkach się tego nie robi, bo w naszej dziedzinie reverse
engineering też jest powszechnie akceptowalną metodą poznawczą.

Studiowanie kodu źródłowego nie jest formą inżynierii wstecznej.
(Za to często wynikiem działania metod inżynierii wstecznej jest kod źródłowy, który
ma właśnie służyć do czytania!)

Kiedyś na filozofii mieliśmy nauczyciela logiki, który próbował nas uczyć podstaw
teorii obliczeń i myślenia algorytmicznego w oparciu o język naturalny.
Gęstwina słów w opisach była tak okropna, że w ogóle nie dało się tego czytać.
Moim zdaniem dużo łatwiej nauczyć się posługiwać zoptymalizowanym językiem do
wyrażania algorytmów (chociażby Pythonem) niż stosować w tym celu polszczyznę.

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

Przeczytałem nawet dziś ten esej Jefa Raskina. Nie zrobił na mnie większego wrażenia,
ale jedno, za co jestem wdzięczny autorowi, to że nie próbuje wciskać czytelnikowi,
że to on jest w posiadaniu absolutnej prawdy, i prawie na każdym kroku podkreśla, że
to są jego opinie, i że tekst ma charakter polemiki z innymi głosami uczestniczącymi
w debacie.

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

Może czasem i tak bywa.
Ja jednak rozumiem frazę "self-documenting code" inaczej.
Dla mnie klejnotem koronnym samodokumentującego się kodu jest ewaluator
metacykliczny.
Można używać języka naturalnego do opisania, jak należy rozumieć dany język
programowania -- ale kiedy się już nauczy myśleć w danym języku programowania, to
można użyć samego tego języka do opisania tego, jak należy rozumieć ten język
programowania.

Ale to nie jest jedyny aspekt. Jakiś czas temu zauważyłem, że studiowanie definicji
przychodzi mi z pewnym trudem -- bo definicje są z natury rzeczy raczej abstrakcyjne.
Z tego też względu lubię mieć w kodzie przykłady użycia różnych definiowanych przez
siebie funkcji. W moim doświadczeniu posiadanie takich konrketnych, namacalnych
przykładów jest najefektywniejszą formą dokumentacji, z jakiej do tej pory
korzystałem.

Jednym z częściej podawanych przeze mnie przykładów są funkcje kombinatoryczne, które
sobie kiedyś napisałem i umieściłem tu:
https://github.com/plande/grand-scheme/blob/master/g
rand/combinatorics.scm

Wśród nich można znaleźć np. taką definicję:

(define (insertions x l)
(match l
([ ]
[[x]])
([head | tail]
[[x head | tail] | (map (lambda (y) [head | y])
(insertions x tail))])))

Definicja nie jest przesadnie skomplikowana -- raptem dwa przypadki do rozważenia --
ale ja i tak nic z tego nie rozumiem (mimo że jak pisałem, to rozumiałem).
Pod spodem mam natomast napisane:

(e.g.
(insertions 'a '(x y z))
===> ((a x y z) (x a y z) (x y a z) (x y z a)))

i jak na to spojrzę, to w oka mgnieniu rozumiem, o co chodzi.
I teraz, można powiedzieć, że to jest taki "test jednostkowy przepleciony z kodem",
ale ja wolę mówić po prostu o przykładzie użycia, bo choć kod rzeczywiście może się
wykonać (i albo nic nie zrobić, gdy wszystko jest OK, albo krzyczeć, gdy wejście nie
zgadza się z wyjściem), to jednak ten kod jest przeznaczony przede wszystkim do
czytania. Jego rolą jest udokumentowanie działania jakiejś funkcji. ("Ale jak to?
Przecież to wykonywalny kod?!")

Tego rodzaju przykłady użycia zdarza mi się przeplatać z komentarzami, tak jak kiedy
pisałem "suitę testową" dla dokumentu SRFI-201. Ale wówczas komentarze nie są "czymś
odrębnym od kodu źródłowego", ani nie są "tylko logistycznie trzymane razem z kodem",
a stanowią z nimi pewną całość narracyjną:

https://github.com/scheme-requests-for-implementatio
n/srfi-201/blob/master/guile/examples.scm

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

Ponownie, jedno drugiego nie wyklucza.

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

No, może problemem jest to, że programowanie nie do końca jest "branżą inżynierską".
To jest ogólnie ciekawe, bo programowanie wydaje mi się bardzo chłonne, jeżeli idzie
o metafory.
Jedni chcą widzieć w tym inżynierię, innym kojarzy się z biologią, dla jeszcze innych
do poezja, dla innych matematyka, czy wreszcie architektura.
Pewnie się już ze sto razy dzieliłem tutaj tym wykładem, ale akurat ten jeden jest
tego wart -- perspektywa profesora informatyki, który został dotkorem nauk
medycznych:

https://www.youtube.com/watch?v=EVkHgKCqAcI

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

Dla mnie raczej znamienne jest to, że Ty twierdzisz, że branża elektroniczna jest
"technicznie najbliższa naszej".
Dla mnie nie jest. Znam dobrych projektantów hardware'u, którzy są bardzo kiepiskimi
programistami. Znam też niezłych programistów, którzy za Chiny nie poradziliby sobie
z hardwarem.
Dla mnie programowanie jest najbliższe pisaniu tekstów. Ba, dla mnie programowanie
jest w przeważającej mierze pisaniem tekstu.
Jeżeli bym szukał tego, co jest najbliższe, to byłyby to prace Gottloba Frege albo
Bertranda Russella.
Sądzę też, że raczej nie zaszkodziłoby programistom zapoznanie się z teorią
literatury (zwłaszcza jeżeli mają tworzyć dokumentację).

Jest nawet taka naprawdę dobra książka, którą na wydziałach filologicznych nazywają
"trojaczkami", zatytułowana "Zarys Teorii Literatury". Dziwi mnie, że nie przerabiają
tego na wydziałach Informatyki. Z tego co widzę, można nawet tutaj ściągnąć:

https://docer.pl/doc/xx0e501

W każdy razie pomiędzy programowaniem a projektem hardware'u jest przepaść.
Współcześnie większość programistów nawet nie będzie miała szans powąchać hardware'u,
na którym będzie chodził ich software.

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

Pewnie różni ludzie robią w pracy różne rzeczy.
Dla mnie w dużej mierze programowanie to jest budowanie języka, w którym mogę
"opowiedzieć system".
Ale rzeczywiście, jak rozglądam się dookoła, to dla większości programistów chyba tak
nie jest.
Dużo widzę różnej maści kultu Cargo.
(Ale tak jak śledzę trendy, to "tworzenie DSLi" chyba nawet jest teraz na czasie)