🚀 go-pugleaf

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/grand/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-implementation/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/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. 

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)