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)

do góry

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

Brawo. Czyli rozumiesz już różnicę pomiędzy artefaktem, który jest na ścieżce
generacji produktu od takiego, który nie jest.
Ta deska referencyjna jest dokumentacją. Ale deska użyta do budowy budy dla psa już
nie jest - dokładnie tak było z diagramami parę postów wcześniej.

Wyprzedzając: tak, można tą deskę referencyjną użyć w innym projekcie jako budulec.
Wtedy przestanie być dokumentacją. Ale to już chyba rozumiesz.

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

Może ktoś kiedyś dopisze. :-D Wikipedia nie jest wykuta w kamieniu.

> Studiowanie kodu źródłowego nie jest formą inżynierii wstecznej.

https://en.wikipedia.org/wiki/Reverse_engineering

Zdumiewająco duża część tego artykułu, w odniesieniu do oprogramowania, dotyczy
właśnie różnych form wyciągania wiedzy z kodu źródłowego. Czytanie kodu źródłowego to
jest właśnie reverse engineering.

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

Jak najbardziej.
Ale Knuth w swojej słynnej książce specjalnie podjał najpierw wysiłek opracowania
języka, który nie miał żadnej znanej implementacji, żeby z jednej strony zapewnić
sobie precyzję opisu, ale z drugiej nie sugerować, że te przykłady są fragmentami
konkretnych projektów. W ten sposób chciał zachować czystość narracji.
Już pisałem - w programowaniu medium jest wspólne, więc ludzie nie odróżniają kodu od
dokumentacji. Zwłaszcza jak jej nie mają. Tak czy siak to są jakieś literki, czasem
cyferki.

> No, może problemem jest to, że programowanie nie do końca jest "branżą
inżynierską".

Podobnie, jak nie każda kupa desek to architektura.
To nie jest tak, że "nie do końca", tylko właśnie "szerzej niż". Powszechne
praktykowanie programowania daleko wykracza poza inżynierię. Dlatego mamy masę
projektów, które z inżynierią nie mają nic wspólnego.

> Dla mnie raczej znamienne jest to, że Ty twierdzisz, że branża elektroniczna jest
"technicznie najbliższa naszej".

Tak to widzę. W sensie - tak to pamiętam z lekcji historii. Również w sensie, że te
dziedziny nawzajem się karmią.

> Sądzę też, że raczej nie zaszkodziłoby programistom zapoznanie się z teorią
literatury (zwłaszcza jeżeli mają tworzyć dokumentację).

No właśnie, ciekawą sprawę poruszyłeś. A dlaczego to programiści mają ją tworzyć?
Dawno temu pisaniem dokumentacji zajmowali się zupełnie inni ludzie. Technical
writing to poważna dyscyplina, nie powierzano tego byle komu. Zauważ, że dokumentacja
w odróżnieniu od kodu jest wizytówką firmy (w wielu projektach zleceniodawca nawet
nie jest zainteresowany kodem źródłowym poza celami archiwizacyjnymi, natomiast
dokumentację dostaje uroczyście), więc ma wpływ na postrzeganie marki. Dlatego pisarz
dokumentacji to była wyższa kasta, niż klepacz kodu.

Może problemem jest to, że obecnie za bardzo przeciążyliśmy pojęcie programisty?
Kiedyś programista to był ktoś, kto pisał kod. A dzisiaj programiści zajmują się
wszystkim, łącznie z psychologią i grafiką użytkową.

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

No właśnie. Może to też jest problem?

> Pewnie różni ludzie robią w pracy różne rzeczy.

Tak. W szczególności, większość nie robi dokumentacji. :-D

--
Maciej Sobczak * http://www.inspirel.com

do góry

środa, 7 kwietnia 2021 o 22:07:20 UTC+2 Maciej Sobczak napisał(a):
> > (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)
> Brawo. Czyli rozumiesz już różnicę pomiędzy artefaktem, który jest na ścieżce
generacji produktu od takiego, który nie jest.
> Ta deska referencyjna jest dokumentacją. Ale deska użyta do budowy budy dla psa już
nie jest - dokładnie tak było z diagramami parę postów wcześniej.

Teraz złap się czegoś, żeby nie spaść z krzesła: buda dla psa też może być
dokumentacją. Wraz z każdą użytą w niej deską.

> > > 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.
> Może ktoś kiedyś dopisze. :-D Wikipedia nie jest wykuta w kamieniu.

To nie o to chodzi.
Chodzi o to, że Ty stwierdziłeś, że "Jeżeli diagram służy do generowania kodu, to
*nie* jest dokumentacją, tak samo jak kod źródłowy (który też służy do generowania
czegoś) nie był dokumentacją", natomiast na moje pytanie o to, dlaczego nie,
odpowiedziałeś linkiem do artykułu na Wikipedii, z którego odpowiedź na to pytanie w
żaden sposób nie wynika.

Definicja, którą podaje Wikipedia, jest bardzo inkluzywna: "rodzajem nadrzędnym" czy
też "genus proximum" dokumentacji jest "dowolny materiał" (czyli bardzo dużo
przedmiotów podpada pod tę deskrypcję), natomiast "różnicą gatunkową" czy też
"differentia specifica" jest to, że "służy do opisania, wyjaśnienia bądź
poinstruowania".

Na ile do tej pory zdołałem się zorientować, definicja dokumentacji, którą Ty masz na
myśli, byłaby taka, że dokumentacja to "materiał, którego główną funkcją jest
opisanie, wyjaśnienie bądź poinstruowanie", albo "materiał stworzony przede wszystkim
w celu opisania, wyjaśnienia" itd.

To jest mniej inkluzywna definicja, i oczywiście możesz się na nią powoływać, ale w
momencie, kiedy powołujesz się na inną definicję, żeby uzasadnić coś, co wynika z
Twojej definicji, wprowadzasz tylko zamieszanie (moim zdaniem dość niepotrzebnie).

Przy okazji - odnośnie Twojego wcześniejszego rozróżnienia na "definiowanie i
dokumentowanie" -- dokładnie z tym samym mamy do czynienia w prawie.
Dokumenty prawne - ustawy, rozpotrządzenia - są zarazem "źródłem prawa" w tym sensie,
że definiują, jakie działania są legalne.

> > Studiowanie kodu źródłowego nie jest formą inżynierii wstecznej.
> https://en.wikipedia.org/wiki/Reverse_engineering
>
> Zdumiewająco duża część tego artykułu, w odniesieniu do oprogramowania, dotyczy
właśnie różnych form wyciągania wiedzy z kodu źródłowego. Czytanie kodu źródłowego to
jest właśnie reverse engineering.

Znamienne, że artykuł zaczyna się od uwagi: "This article has multiple issues."
W ogólności jest raczej dość długi, więc jeżeli jest jakieś zdanie albo akapit, który
miałbyś na myśli, to pewnie wskazanie albo przytoczenie go ułatwiłoby komunikację.
Moją uwagę przykuło zdanie (na początku sekcji 2.3 pt. "Source code"):
"A number of UML tools refer to the process of importing and analysing source code to
generate UML diagrams as "reverse engineering.""

Co jest znamienne, bo po pierwsze pokazuje, jak mętne i niedookreślone jest pojęcie
"reverse engineeringu", a po drugie, że zwolennicy najwidoczniej UML uważają, że ich
język jest "notacją, w której wyraża się źródłowa intencja budowy systemu". Podczas
gdy tym czasem bardzo wiele procesów wytwarzania oprogramowania w ogóle nie
uwzględnia UMLa na żadnym ze swoich etapów, i jeżeli w wyniku "reverse engineeringu"
za pomocą wspomnianych narzędzi otrzymasz jakiś artefakt, to on nie będzie żadnym
odtworzeniem czegokolwiek.

> > 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.
> Jak najbardziej.
> Ale Knuth w swojej słynnej książce specjalnie podjał najpierw wysiłek opracowania
języka, który nie miał żadnej znanej implementacji, żeby z jednej strony zapewnić
sobie precyzję opisu, ale z drugiej nie sugerować, że te przykłady są fragmentami
konkretnych projektów. W ten sposób chciał zachować czystość narracji.

To też jest przykład, który dla mnie jest znamienny: książka Knutha jest raczej
słynna z tytułu i nazwiska autora, niż z tego, żeby była popularną lekturą wśród
młodzieży.
Po części problem wynika stąd, że Knuth zaczął ją pisać w latach 60., kiedy obsługa
komputerów często wymagała zaznajamiania się z ich partykularnymi zestawami
instrukcji.
Wtedy stworzenie asemblera "MIX" mogło wydawać się racjonalne, bo rzeczywiście
wiązało się z pewnymi umiejętnościami, które były wymagane.
Natomiast od tamtej pory wiele się zmieniło: upowszechnił się język C oraz inne
języki wysokiego poziomu, dzięki którym "ten sam program" można uruchamiać na różnych
zestawach instrukcji.
Pojawiły się też komputery osobiste, które za pomocą BASICa spopularyzowały
"symboliczne programowanie", i zredefiniowały rozumienie tego, czym jest
programowanie, wśród kolejnego pokolenia programistów.
I tym sposobem książka Knutha - mimo że porusza tematykę uniwersalną - nie porusza
jej w uniwersalny sposób.
Dla mnie pewnym kontrastem dla tej książki jest "Struktura i Interpretacja Programów
Komputerowych", która też porusza uniwersalne kwestie, ale w sposób bardziej
uniwersalny, bo pomimo, że używa języka, którego też nikt nie używa, używa języka,
który - w przeciwieństwie do asemblera - jest ekspresywny.

To przywodzi na myśl anegdotę opowiedzianą przez Breta Victora o reakcji von Neumanna
na to, jak jeden z jego studentów opracował asembler, dzięki któremu nie trzeba było
programować w kodzie maszynowym:
https://www.youtube.com/watch?v=8pTEmbeENF4

> > No, może problemem jest to, że programowanie nie do końca jest "branżą
inżynierską".
> Podobnie, jak nie każda kupa desek to architektura.
> To nie jest tak, że "nie do końca", tylko właśnie "szerzej niż". Powszechne
praktykowanie programowania daleko wykracza poza inżynierię. Dlatego mamy masę
projektów, które z inżynierią nie mają nic wspólnego.

No może tak bardziej.

> > Dla mnie raczej znamienne jest to, że Ty twierdzisz, że branża elektroniczna jest
"technicznie najbliższa naszej".
> Tak to widzę. W sensie - tak to pamiętam z lekcji historii. Również w sensie, że te
dziedziny nawzajem się karmią.

Dla mnie branża elektroniczna jest pod wieloma względami bliższa np. hydraulicznej. W
tym sensie, że jest trochę analogii w działaniu (choć oczywiście wiele zjawisk, jak
np. indukcja, nie ma bezpośrednich odpowiedników). Natomiast historycznie wydziały
komputerowe powstawały chyba równolegle na przy wydziałach inżynierii elektrycznej i
matematyki.

> > Sądzę też, że raczej nie zaszkodziłoby programistom zapoznanie się z teorią
literatury (zwłaszcza jeżeli mają tworzyć dokumentację).
> No właśnie, ciekawą sprawę poruszyłeś. A dlaczego to programiści mają ją tworzyć?
Dawno temu pisaniem dokumentacji zajmowali się zupełnie inni ludzie. Technical
writing to poważna dyscyplina, nie powierzano tego byle komu. Zauważ, że dokumentacja
w odróżnieniu od kodu jest wizytówką firmy (w wielu projektach zleceniodawca nawet
nie jest zainteresowany kodem źródłowym poza celami archiwizacyjnymi, natomiast
dokumentację dostaje uroczyście), więc ma wpływ na postrzeganie marki. Dlatego pisarz
dokumentacji to była wyższa kasta, niż klepacz kodu.

Może i tak. Z drugiej strony, dla mnie kod źródłowy również jest dokumentacją, i
wiele "reguł dobrego pisania" obowiązuje również przy pracy z kodem.
(Tzn. oczywiście wiele kodu nie stosuje się do tych reguł).
Pod tym względem bardzo podobała mi się ta prezentacja twórcy frameworku Rails dla
Ruby'ego, w której porusza związki programowania z siedemnastowieczną poezją
francuską:
https://www.youtube.com/watch?v=9LfmrkyP81M

> Może problemem jest to, że obecnie za bardzo przeciążyliśmy pojęcie programisty?
Kiedyś programista to był ktoś, kto pisał kod. A dzisiaj programiści zajmują się
wszystkim, łącznie z psychologią i grafiką użytkową.

Z jednej strony sobie myślę, że może trochę tak. Z drugiej -- ja nadal piszę kod, i
to głównie ten kod jest owocem mojej pracy (nawet jeżeli do napisania tego kodu muszę
zdobyć wiedzę z wielu innych dziedzin).

> > 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.
> No właśnie. Może to też jest problem?

Może jest na wielu poziomach. Ale wydaje mi się, że przede wszystkim pokazuje, jak
bardzo "wyabstrahowaną" aktywnością stało się programowanie.

do góry

Niestety nie umiem zmusić Google'a, żeby pokazał do czego Twoja wiadomość się odnosi,
ale z treści wnioskuję, że może to być odpowiedź do mnie. Czuję się więc wywołany do
tablicy.

> Na szczęście
> nie jesteś moim podwładnym

Wygląda na to, że to są dwa szczęścia na raz! :-D

> Nawet rozumiem twój upór - wyuczono cię że pisze się program a jak
> program już jest to osobną sprawą jest zrobienie dokumentacji.

Pudło. Ostatnio raczej mam do czynienia z czymś odwrotnym - najpierw powstaje
dokumentacja a dopiero potem program.
W sumie to jest chyba najlepsza metoda, żeby nie dochodziło do wypaczeń typu
"napisaliśmy samodokumentujący się kod".

> Masz po prostu single core brain - jednowątkowo myślisz i nie
> rozumiesz że jeden i ten sam byt może należeć do dwóch klas
> abstrakcji.

Dwóch? Chyba żartujesz. My tu już nawet ustaliliśmy, że kod jest również poezją. :-)

> Za dużo Javy
> za mało C++.

Musisz tu być nowy.

> Ale dla złagodzenia objawów przepisałbym
> na początek po 5 stron z Clean Code Martina. dziennie.

Jeśli właśnie w ten sposób zdobywałeś kwalifikacje, to zaczynam rozumieć różnice w
perspektywie.
A właściwie to dlaczego Martin napisał książkę? Nie wystarczyło napisać kod? Hm...

Proponuję dla dobra pozostałych grupowiczów podsumować, że w tej dyskusji nie
ustalono wspólnego stanowiska.
No chyba że pojawiłby się jakiś nowy punkt zaczepienia, to ja chętnie.

--
Maciej Sobczak * http://www.inspirel.com

do góry

> > Ostatnio raczej mam do czynienia z czymś odwrotnym - najpierw powstaje
dokumentacja a dopiero potem program.
> Też można: skoro płacą jak za programowanie, to po co pisać
> program,

Znowu jesteś w błędzie. To właśnie system rozliczeniowy, w którym płaci się za
program, prowadzi do tego, że nie powstaje dokumentacja. A tak powstaje jedno i
drugie.

> papier (docx) wszystko przyjmie

Znowu jesteś w błędzie. Ponieważ dokumentacja zaczyna powstawać wcześniej, to ma też
największą ilość poprawek. To nie jest tak, że tam jest cokolwiek.

> Najlepiej - MOIM ZDANIEM - jest pisać program i dokumentację oraz
> testy jednocześnie.

Znowu jesteś w błędzie, bo z tego wynika, że te trzy rzeczy powstają w próżni. Otóż
one nie powstają w próżni, tylko na podstawie czegoś. I te zależności wpływają na
sensowną kolejność wykonywania tych rzeczy. I ta kolejność będzie jeszcze dodatkowo
zależna od logistyki, np. dostępności sprzętu.
Istnieje też zupełnia poważna podstawa do tego, żeby testy i program były robione
niezależnie, co czyni postulat jednoczesności całkiem bezprzedmiotowym. Z grafu
zależności wiadomo tylko tyle, że kiedyś potrzebne będą zarówno testy, jak i program
(np. po to, żeby w ogóle można było te testy puścić).

> >A właściwie to dlaczego Martin napisał książkę? Nie wystarczyło napisać kod?
> Przeczytaj to się dowiesz. Może się zdziwisz ale w tej książce
> jest też i kod.

Ale to nie odpowiada na pytanie, po co napisał książkę. Kod by napisał, taki
samokomentujący, i by stykło. Nie?

--
Maciej Sobczak * http://www.inspirel.com

do góry

sobota, 10 kwietnia 2021 o 16:26:13 UTC+2 Maciej Sobczak napisał(a):

> Proponuję dla dobra pozostałych grupowiczów podsumować, że w tej dyskusji nie
ustalono wspólnego stanowiska.

Ja bym powiedział, że jest znacznie gorzej: nie udało się nawet ustalić wspólnego
rozumienia znaczeń słów, ani sposobów posługiwania się prawami logiki. Na rozmowę o
stanowiskach nie było nawet szans.

> > >A właściwie to dlaczego Martin napisał książkę? Nie wystarczyło napisać kod?
> > Przeczytaj to się dowiesz. Może się zdziwisz ale w tej książce
> > jest też i kod.
> Ale to nie odpowiada na pytanie, po co napisał książkę. Kod by napisał, taki
samokomentujący, i by stykło. Nie?

Równie dobrze mógłbyś pytać, dlaczego nauczyciele prowadzą z uczniami lekcje
czytania. Przecież daliby im do rąk elementarz, w którym jest wszystko wyjaśnione, i
by stykło. Nie?

Problem jest podobny do kwestii udostępniania wersji binarnej kompilatora, którego
kod źródłowy jest dostępny.
Kod źródłowy kompilatora na niewiele się zda, jeżeli nie będziesz miał narzędzia,
przy pomocy którego mógłbyś ten kod skompilować. Na niewiele się zda, czyli będzie
służył wyłącznie jako dokumentacja, bo nie będzie sposobu, żeby ten kod wykonać
(chyba że ręcznie go "skompilujesz" do jakiegoś języka, który już jest zrozumiały dla
komputera -- ale to pod warunkiem, że sam rozumiesz język w którym i dla którego jest
napisany kompilator).

Błąd, jaki Ty popełniasz, polega na tym, że ze stwierdzenia, że coś jest
dokumentacją, próbujesz wyciągać wniosek, że owo coś jest wyczerpującą albo jedyną
potrzebną dokumentacją.

Samodokumentujący kod zawiera wszystko, co jest potrzebne do tego, żeby zrozumieć,
jak jakiś system działa. Nie zawiera za to, na przykład, informacji, jak albo w jakim
celu ten system powstał, jak można ten system rozwijać, ani jak się tego systemu
używa. Nie zawiera też informacji o tym, w jaki sposób należy pisać i czytać kod taki
źródłowy -- to jest osobna umiejętność, którą programista musi rozwinąć. Książka
Martina jest (kiepskim bo kiepskim, ale jednak) materiałem, który ma trenować tę
umiejętność.

do góry

sobota, 10 kwietnia 2021 o 16:26:13 UTC+2 Maciej Sobczak napisał(a):

> > papier (docx) wszystko przyjmie
>
> Znowu jesteś w błędzie. Ponieważ dokumentacja zaczyna powstawać wcześniej, to ma
też największą ilość poprawek. To nie jest tak, że tam jest cokolwiek.

Zabawne, że dosłownie kilka postów wcześniej pisałeś o "różnicy pomiędzy artefaktem,
który jest na ścieżce generacji produktu od takiego, który nie jest".
To dokumentacja, która powstaje przed kodem, jest, czy nie jest, na ścieżce generacji
produktu?
Jeżeli nie jest, to wówczas - by użyć Twoich słów - "jest tak, że tam jest
cokolwiek".
A jeżeli jest, to - według Twojej definicji - taka dokumentacja "nie jest
dokumentacją".

do góry

> > Ale to nie odpowiada na pytanie, po co napisał książkę. Kod by napisał, taki
samokomentujący, i by stykło. Nie?
> Równie dobrze mógłbyś pytać, dlaczego nauczyciele prowadzą z uczniami lekcje
czytania.

Zgadzam się, że na logiczną dyskusję chyba nie ma już szans...

> Problem jest podobny do kwestii udostępniania wersji binarnej kompilatora, którego
kod źródłowy jest dostępny.

... tak, jestem tego coraz bardziej pewny. Nie ma szans.

> Błąd, jaki Ty popełniasz, polega na tym, że ze stwierdzenia, że coś jest
dokumentacją, próbujesz wyciągać wniosek, że owo coś jest wyczerpującą albo jedyną
potrzebną dokumentacją.

Bo właśnie tak to działa w powszechnym odbiorze. W sensie - ktoś, kto nie napisał
dokumentacji stwierdza, że przecież jego kod jest tak bardzo samodokumentujący, że
już niczego więcej nie trzeba. I tak to zostaje.
Więc warto jednak dbać o rozróżnianie pojęć, w przeciwnym razie pogubimy się w ich
rozmyciach.
Więc zadbajmy o takie rozróżnienie: kod *nie* jest dokumentacją. Może sobie być
poezją w jakimś pozainżynierskim kontekście (no chyba że poeci zgłoszą jakiś
sprzeciw, np. poczują się obrażeni albo coś), ale nie jest dokumentacją.

> Samodokumentujący kod zawiera wszystko, co jest potrzebne do tego, żeby zrozumieć,
jak jakiś system działa.

"Koń jaki jest, każdy widzi." Wiesz, skąd to zdanie pochodzi? Z bardzo poważnego
źródła. Ale jednak z biegiem czasu zaczęliśmy wymagać więcej, więc nawet w tych
poważnych źródłach już takich zdań nie ma.

> Nie zawiera za to, na przykład, informacji [...]

Bo nie jest dokumentacją.

> Książka Martina jest (kiepskim bo kiepskim, ale jednak) materiałem, który ma
trenować tę umiejętność.

Umiejętność czego? Pisania dobrej jakości kodu? No i świetnie, oby więcej takich
książek.
Nadal jednak kod nie jest dokumentacją.

--
Maciej Sobczak * http://www.inspirel.com

do góry

> To dokumentacja, która powstaje przed kodem, jest, czy nie jest, na ścieżce
generacji produktu?

A czy kod może być wygenerowany automatycznie *z tego* artefaktu, tak jak kod
wykonywalny może być wygenerowany automatycznie z kodu źródłowego?
Bo właśnie na tym polegało rozróżnienie w diagramach.

> Jeżeli nie jest, to wówczas - by użyć Twoich słów - "jest tak, że tam jest
cokolwiek".

W żadnym przypadku nie jest tam cokolwiek.
Tzn. ja piszę o inżynierii. Nie wiem, jak tam u poetów.

--
Maciej Sobczak * http://www.inspirel.com

do góry

poniedziałek, 12 kwietnia 2021 o 17:58:26 UTC+2 Maciej Sobczak napisał(a):
> > > Ale to nie odpowiada na pytanie, po co napisał książkę. Kod by napisał, taki
samokomentujący, i by stykło. Nie?
> > Równie dobrze mógłbyś pytać, dlaczego nauczyciele prowadzą z uczniami lekcje
czytania.
> Zgadzam się, że na logiczną dyskusję chyba nie ma już szans...

Szanse są zawsze. Tylko to wymaga przede wszystkim wysiłku zdefiniowania używanych w
dyskusji terminów, i trzymania się tych definicji. Wierzę, że stać Cię na taki
wysiłek.

> > Błąd, jaki Ty popełniasz, polega na tym, że ze stwierdzenia, że coś jest
dokumentacją, próbujesz wyciągać wniosek, że owo coś jest wyczerpującą albo jedyną
potrzebną dokumentacją.
> Bo właśnie tak to działa w powszechnym odbiorze. W sensie - ktoś, kto nie napisał
dokumentacji stwierdza, że przecież jego kod jest tak bardzo samodokumentujący, że
już niczego więcej nie trzeba. I tak to zostaje.

Jak to mówią, "ogólnie różnie bywa".
Jeżeli rzeczywiście niczego więcej nie potrzeba, to czas, który nie został
wydatkowany na robienie dokumentacji, to czas zaoszczędzony.
A jeżeli potrzeba czegoś więcej, to ta potrzeba prędzej czy później da o sobie znać w
jakimś procesie.
Pisanie dokumentacji po to, żeby była napisana dokumentacja, to kiepski pomysł.

Znów mogę posłużyć się przykładem. Ostatnio zajmowałem się trochę kwestią parsowania
z zachowaniem komentarzy i białych znaków. Napisałem parser i podzieliłem się nim ze
swoim przyjacielem, z którym często sobie rozmawiamy na różne tematy:

https://github.com/panicz/grasp-android/blob/master/
javor/parse.scm

w odpowiedzi przyjaciel napisał swoją wersję parsera, którą podzielił się ze mną:

https://github.com/drcz/random-crap/blob/master/pod-
jaworem.scm

Ponieważ "mówimy wspólnym językiem", i obaj wyrobiliśmy w sobie nawyk pisania
przykładów w kodzie źródłowym, żadna dodatkowa dokumentacja nie była potrzebna. Nic
by nie wniosła.

> Więc warto jednak dbać o rozróżnianie pojęć, w przeciwnym razie pogubimy się w ich
rozmyciach.

Przede wszystkim należy zacząć od zdefiniowania pojęć.

> Więc zadbajmy o takie rozróżnienie: kod *nie* jest dokumentacją. Może sobie być
poezją w jakimś pozainżynierskim kontekście (no chyba że poeci zgłoszą jakiś
sprzeciw, np. poczują się obrażeni albo coś), ale nie jest dokumentacją.

Według JAKIEJ definicji "dokumentacji"?

> > Samodokumentujący kod zawiera wszystko, co jest potrzebne do tego, żeby
zrozumieć, jak jakiś system działa.
> "Koń jaki jest, każdy widzi." Wiesz, skąd to zdanie pochodzi? Z bardzo poważnego
źródła. Ale jednak z biegiem czasu zaczęliśmy wymagać więcej, więc nawet w tych
poważnych źródłach już takich zdań nie ma.

Nie rozumiem.

> > Nie zawiera za to, na przykład, informacji [...]
>
> Bo nie jest dokumentacją.

Według JAKIEJ definicji?

> > Książka Martina jest (kiepskim bo kiepskim, ale jednak) materiałem, który ma
trenować tę umiejętność.
> Umiejętność czego?

Pisania kodu, do którego zrozumienia nie potrzeba dodatkowej dokumentacji.

> Nadal jednak kod nie jest dokumentacją.

Według JAKIEJ definicji?

do góry