Hej

Wiadomo wszem i wobec, że w trakcie piania kodu warto go opisywać
komentarzami. Trzeba wyważyć kwestię użyteczności opisu kontra czas
potrzebny na stworzenie opisu. Skrajność w jedną stronę:
for(i=0;i<5;i++) informacja że i to licznik pętli jest zbędna. Skrajność
w drugą stronę: kodujemy projekt, po dwóch miesiącach w trakcie
tworzenia jakiejś funkcjonalności okazuje się, że dla obecnych potrzeb
trzeba wstawić w jakąś funkcję nieruszaną od dawien dawna fragment
kodu, zupełnie niekorespondujący z nazwą funkcji i z tym co ona robi -
ot po prostu to jest najlepsze miejsce dla tej wstawki. Wiadomo - opisać
sytuację trzeba.

To są przypadki skrajne, pomiędzy którymi jest milion pierdylionów
stanów pośrednich. Amatorskie podejście to "hmmm tego mogę kierdyś nie
zakumać - opiszę", ale i "dam radę - szkoda czasu". Co może doprowadzić
do tego, że z jednej strony opisujemy niepotrzebnie coś co i tak każdy
przedszkolak zakuma lub z drugiej stony przeceniamy się i nie opisujemy
czegoś do czego dzięki opisowi mogli byśmy "szybciej wrócić".

Czy jest jakieś optymalne rozwiązanie ? Przestrzeń rozwiązań chyba spora :)

do góry

On Sat, 21 Dec 2013 20:09:07 +0100, Przemys??w D?bski
<p...@g...pl> wrote:

>Hej
>
>Wiadomo wszem i wobec, że w trakcie piania kodu warto go opisywać
>komentarzami. Trzeba wyważyć kwestię użyteczności opisu kontra czas
>potrzebny na stworzenie opisu. Skrajność w jedną stronę:
>for(i=0;i<5;i++) informacja że i to licznik pętli jest zbędna. Skrajność
>w drugą stronę: kodujemy projekt, po dwóch miesiącach w trakcie
>tworzenia jakiejś funkcjonalności okazuje się, że dla obecnych potrzeb
>trzeba wstawić w jakąś funkcję nieruszaną od dawien dawna fragment
>kodu, zupełnie niekorespondujący z nazwą funkcji i z tym co ona robi -
>ot po prostu to jest najlepsze miejsce dla tej wstawki. Wiadomo - opisać
>sytuację trzeba.
>
>To są przypadki skrajne, pomiędzy którymi jest milion pierdylionów
>stanów pośrednich. Amatorskie podejście to "hmmm tego mogę kierdyś nie
>zakumać - opiszę", ale i "dam radę - szkoda czasu". Co może doprowadzić
>do tego, że z jednej strony opisujemy niepotrzebnie coś co i tak każdy
>przedszkolak zakuma lub z drugiej stony przeceniamy się i nie opisujemy
>czegoś do czego dzięki opisowi mogli byśmy "szybciej wrócić".
>
>Czy jest jakieś optymalne rozwiązanie ? Przestrzeń rozwiązań chyba spora :)

Proponuje ksiazke

A Guide to Persuasive Programming in Java

by Jerud J. Mead , Anil M. Shende

Mniej wiecej, komentowanie powinno spelnaic role podobna do
mechanizmow "programming by contract"

A.L.

do góry

Użytkownik "A.L." napisał w wiadomości grup
dyskusyjnych:tdrbb9leujgvoi2qqu2eq0npvub8l7hirp@4ax.
com...

>Mniej wiecej, komentowanie powinno spelnaic role podobna do
>mechanizmow "programming by contract"

Brak komentarza wynika tylko i wyłącznie z lenistwa. Ludzie zwykli w
najrozmaitszy sposób racjonalizować swoje lenistwo i są w tym naprawdę
dobrzy. Więc będą nawijać coś o samokomentującym się kodzie, będą pisali
oczywiste rzeczy nie wymagają, będą twierdzili, że szkoda czasu na komentarz
(bo niby lepiej poświecić go na klepanie kodu na godzinę przed deadline).
Ale wszystko to ma jedynie zamaskować wrodzone rodzajowi ludzkiemu
nieróbstwo.

Oczywiście będą tacy, którzy wysuną argument, że komentarz nie odpowiadający
temu co jest w kodzie jest szkodliwy. I będą mieli trochę racji. Dokładnie
tyle, żebyśmy wysnuli wniosek, iż cnotą jest utrzymywanie porządku tak w
kodzie, jak i w komentarzach oraz innej dokumentacji.

Moim zdaniem, jeżeli używa się Dobrego Języka Dostatecznie Wysokiego Poziomu
(DJDWP), to na każdą linijkę programu powinny przypadać dwie linijki
komentarza. Lub nawet więcej.

Dlaczego? Bo DJDWP jest tak zwięzłą notacją, że w jednej linijce można
zrobić taki ogrom pracy, iż zasługuje ona na więcej niż jedną linijkę
komentarza.

A ponadto nie jest głupie pisanie komentarza choćby po to, aby zrozumieć
czego się nie rozumie we własnym programie. No chyba że ktoś jest A.L. i
potrafi pisać programy od razu z klawiatury heksadecymalnej... i to
bezbłędnie działające. Mistrz tak doskonały nawet jak milczy, to i tak
komentuje swoim milczeniem dzieło jakie stworzył.

do góry

On Saturday, December 21, 2013 8:09:07 PM UTC+1, Przemysłąw Dębski wrote:
> Wiadomo wszem i wobec, że w trakcie piania kodu warto go opisywać
> komentarzami.

Nie no, poczytaj guru ruchu agile, niejakiego "Uncle Boba". Tenże
twierdzi, że im mniej komentarzy, tym lepiej. Bo komentarze to
dodatkowy koszt, bo trzeba aktualizować, itd.

> To są przypadki skrajne, pomiędzy którymi jest milion pierdylionów
> stanów pośrednich. Amatorskie podejście to "hmmm tego mogę kierdyś nie
> zakumać - opiszę", ale i "dam radę - szkoda czasu". Co może doprowadzić
> do tego, że z jednej strony opisujemy niepotrzebnie coś co i tak każdy
> przedszkolak zakuma lub z drugiej stony przeceniamy się i nie opisujemy
> czegoś do czego dzięki opisowi mogli byśmy "szybciej wrócić".
>
> Czy jest jakieś optymalne rozwiązanie ? Przestrzeń rozwiązań chyba spora :)

Staram się, żeby klasy w najprostszym przypadku posiadały opis do czego
ta klasa jest i ewentualnie w jakim miejscu jest używana (np. "wyznacza
różnice między obiektami Foo, używana wewnętrznie przez serwis FooDiff").
Chodzi o to, aby szybko orientować się w strukturze kodu.

W kodzie komentuję miejsca nieoczywiste, hacki i inne takie. Raz, że to
dokumentuje tę nieoczywistość, dwa unika się setnej odpowiedzi na pytania
w stylu "a czemu tak to idiotycznie napisałeś?".

w.

do góry

W dniu 2013-12-21 20:38, A.L. pisze:

> Proponuje ksiazke
>
> A Guide to Persuasive Programming in Java
>
> by Jerud J. Mead , Anil M. Shende
>
> Mniej wiecej, komentowanie powinno spelnaic role podobna do
> mechanizmow "programming by contract"

Oczywiście książki w międzyczasie od mojego postu do Twojej odpowiedzi
nie przeczytałem :) Natomiast google zapuszczone na hasło "programming
by contract" zwróciło wyniki z którymi się zapoznałem i faktycznie idea
ma sens w odniesieniu do komentowania/opisywania kodu. Praktyka
pokazuje, że gdy nie ma pomysłu jak podejść do tematu opisywania, z
reguły pokazuje się jak dany fragment kodu działa bez osadzania go w
kontekście roli jaką pełni i stawianych wymagań. Późniejsze modyfikacje
mogą rolę lepiej lub gorzej zachować, natomiast kto by o wymaganiach
pamiętał. Dzięki.

Pozdrawiam

do góry

On Sat, 21 Dec 2013 22:57:26 +0100, Przemysłąw Dębski
<p...@g...pl> wrote:

>W dniu 2013-12-21 20:38, A.L. pisze:
>
>> Proponuje ksiazke
>>
>> A Guide to Persuasive Programming in Java
>>
>> by Jerud J. Mead , Anil M. Shende
>>
>> Mniej wiecej, komentowanie powinno spelnaic role podobna do
>> mechanizmow "programming by contract"
>
>Oczywiście książki w międzyczasie od mojego postu do Twojej odpowiedzi
>nie przeczytałem :) Natomiast google zapuszczone na hasło "programming
>by contract" zwróciło wyniki z którymi się zapoznałem i faktycznie idea
>ma sens w odniesieniu do komentowania/opisywania kodu. Praktyka
>pokazuje, że gdy nie ma pomysłu jak podejść do tematu opisywania, z
>reguły pokazuje się jak dany fragment kodu działa bez osadzania go w
>kontekście roli jaką pełni i stawianych wymagań. Późniejsze modyfikacje
>mogą rolę lepiej lub gorzej zachować, natomiast kto by o wymaganiach
>pamiętał. Dzięki.
>
>Pozdrawiam

Frameework do programming by contract do Javy zrobil Google. NAzywa
sie Cofoja. Contract programming for Java. Ogolnie dostepne.

A.L.

do góry

On Sat, 21 Dec 2013 13:26:35 -0800 (PST), Wojciech Muła
<w...@g...com> wrote:

>On Saturday, December 21, 2013 8:09:07 PM UTC+1, Przemysłąw Dębski wrote:
>> Wiadomo wszem i wobec, że w trakcie piania kodu warto go opisywać
>> komentarzami.
>
>Nie no, poczytaj guru ruchu agile, niejakiego "Uncle Boba". Tenże
>twierdzi, że im mniej komentarzy, tym lepiej. Bo komentarze to
>dodatkowy koszt, bo trzeba aktualizować, itd.
>
Po co cytujesz kretynow?...

A.L.

do góry

On 21/12/2013 22:56, A.L. wrote:
> On Sat, 21 Dec 2013 13:26:35 -0800 (PST), Wojciech Muła=
>>
>> Nie no, poczytaj guru ruchu agile, niejakiego "Uncle Boba". Tenże
>> twierdzi, że im mniej komentarzy, tym lepiej. Bo komentarze to
>> dodatkowy koszt, bo trzeba aktualizować, itd.
>>
> Po co cytujesz kretynow?...

Roberta Martina?
On pisze o takich rzeczach, że jeśli masz napisać:
int tFi; // temporary final interest
to lepiej napisać:
int temporaryFinalInterest;

To kretynizm? Mnie się wydaje sensowne.

do góry

On Sun, 22 Dec 2013 10:00:55 +0000, Andrzej Jarzabek
<a...@g...com> wrote:

>On 21/12/2013 22:56, A.L. wrote:
>> On Sat, 21 Dec 2013 13:26:35 -0800 (PST), Wojciech Muła=
>>>
>>> Nie no, poczytaj guru ruchu agile, niejakiego "Uncle Boba". Tenże
>>> twierdzi, że im mniej komentarzy, tym lepiej. Bo komentarze to
>>> dodatkowy koszt, bo trzeba aktualizować, itd.
>>>
>> Po co cytujesz kretynow?...
>
>Roberta Martina?
>On pisze o takich rzeczach, że jeśli masz napisać:
>int tFi; // temporary final interest
>to lepiej napisać:
>int temporaryFinalInterest;
>
>To kretynizm? Mnie się wydaje sensowne.

Mnie tez. Nie kwestionuje tego. Komentowalem uwage o komentarzach. Na
zasadzie "lyzki dziegciu w beczce miodu", trace zaufanie do
wszystkiego o czym pisze.

W Ameryce jest caly ruch facetow ktorym sie nei chce parcowac, za to
postanowili zostac "gurus". Zaparszani na seminaria po 10tysiecy
dolcow za godzine.

Krok wstepny do zostanai "guru" to negowanie wszystkiego do do tej
pory uwzano a "dobraraktyke" Stad mamy takie nosnensy jak extreme
programming, Agile i rozne takie. W szczegolnsoci "nie tzreba
dokumetacji bo wszystko co tzreba wiedziec jest w kodzie"

No i oczywiscie, w pzremysle jest kupa kretynow ktorzyo kupuja. Bo
posiedzial to "guru".A opinia guru to zreczny dupochron.

I tak sie biznes kreci

A.L.

do góry

Dnia Sun, 22 Dec 2013 11:05:14 -0600, A.L. napisał(a):

> W Ameryce jest caly ruch facetow ktorym sie nei chce parcowac, za to
> postanowili zostac "gurus". Zaparszani na seminaria po 10tysiecy
> dolcow za godzine.

I tymi guru sami sie obwolali, kazali sobie placic fortune za porady, a
reszta swiata lyknela i zaczela placic?

--
pozdro
R.e.m.e.K

do góry