Jak wytłumaczyć koledze, że rozwolnienie w pisaniu komentarzy jest złe?

1

Żeby nie było: jest on generalnie mądry i utalentowany, ale nie interesuje się developerką.

Twierdzi, że należy pisać co kod robi, a nie tylko dlaczego, bo wtedy nie musisz się męczyć i czytać kodu tylko czytasz po ludzku + jak ktoś nie umie programować to też zrozumie.
Twierdzi też, że przy każdej zmianie kodu należy dopisywać w komentarzu brancha zmiany, projekt, użykotwnika i datę mimo używania kontroli wersji. Czyli coś takiego:

# function sum 2 vectors
sum2Vect <- function(a + b){
  a + b; # changed in BP2433, Kowalski 2017-01-01 # changed in BP 2478, Nowak 2017-05-05
}
2
 a + b; # changed in BP2433, Kowalski 2017-01-01 # changed in BP 2478, Nowak 2017-05-05

Jeśli już musi być to w kodzie oznaczone, spokojnie wystarczyłoby

a + b; # BP2433, BP2478

Te wszystkie Nowaki to nadmiarowa informacja do niczego w kodzie nie potrzebna.

wtedy nie musisz się męczyć i czytać kodu tylko czytasz po ludzku +

jak ktoś nie umie programować to też zrozumie.

Jak ktoś nie umie programować to po co do kodu zagląda.

należy pisać co kod robi, a nie tylko dlaczego

Co kod robi to powinno wynikać z nazw funkcji, zmiennych, klas itp.

wtedy nie musisz się męczyć i czytać kodu tylko czytasz po ludzku

I tak się trzeba męczyć, bo takie komentarze zaraz się dezaktualizują i są bezwartościowe.

4

Zrób koledze kurs z obsługi Tortoise, ew. FishEye + JIRA.
Jeśli tego nie macie (ani odpowiednika) to trochę kolegę rozumiem.
Zmiana musi być udokumentowana - tyle że normalnie nie robi się tego w kodzie a raczej w SVN/GIT a najlepiej w tym co napisałem wyżej (gdzie masz dodatkowo komentarze innych, załączniki, powiązane commity itd).

To jak to wygląda teraz przypomina czasy sprzed VCS.

7
  1. Kod sie zmienia, komentarze nie. Za miesiąc komentarz będzie twierdzil że kod robi X a kod będzie robił Y. Jedyne pewne źródło informacji to kod
  2. Ktoś może przypadkiem usunąć informacje kto i kiedy modyfikował, może zmieni się system ticketów i stare ID będą w ogóle bezwartościowe? Jedyne pewne źródło informacji na temat historii zmian to system kontroli wersji.
  3. Jak ktoś nie umie programować to niech poprosi o dokumentacje a nie zagląda do kodu.
  4. Kolega to idiota i jesli masz w robocie więcej takich to zalecam taktykę "ostatni gasi światło" i szybką ewakuacje.
0
Shalom napisał(a):
  1. Kod sie zmienia, komentarze nie. Za miesiąc komentarz będzie twierdzil że kod robi X a kod będzie robił Y. Jedyne pewne źródło informacji to kod
  2. Ktoś może przypadkiem usunąć informacje kto i kiedy modyfikował, może zmieni się system ticketów i stare ID będą w ogóle bezwartościowe? Jedyne pewne źródło informacji na temat historii zmian to system kontroli wersji.
  3. Jak ktoś nie umie programować to niech poprosi o dokumentacje a nie zagląda do kodu.
  4. Kolega to idiota i jesli masz w robocie więcej takich to zalecam taktykę "ostatni gasi światło" i szybką ewakuacje.

Kolega odpowie tak:
ad 1: komentarze też trzeba zmieniać jak zmieniasz kod
ad 2: to nie usuwaj
ad 3: a jak np. masz pół roku przerwy z programowaniem w R i wrócisz po pół roku to będziesz pamiętał co dana funkcja robi?
ad 4: Kolega nie jest idiotą tylko po prostu nie jest developerem. To matematyk w matematyce rozwala bardzo trudne rzeczy.

2
  1. Jasne, ale nikt tego nie robi :D
  2. Zasada ograniczonego zaufania ;)
  3. Jeśli kod jest czytelny, to tak
  4. Jeśli nie jest specjalistą w dziedzinie X a mimo to próbuje forsować w tej dziedzinie swoje pomysły to znaczy ze jest głupi. Jego zdolnosci matematyczne nie mają tu żadnego znaczenia.
0

ad 1 dlatego musimy to robić.
ad 2 ... nie wiem co by powiedział
ad 3 ... a ja nie (:D)

3

Czasami zwięzły komentarz co dany kod robi się przydaje i w niczym nie szkodzi. Tylko że komentarz nie powinien opisywać samego kodu, czyli JAK coś działa, a CO i DLACZEGO.

Przykład: masz moduł implementujacy algorytm Paxos - warto zamieścić komentarz wskazujący na to, że to implementacja Paxos, napisać, która to odmiana Paxosa, dać nawiązanie do artykułu i napisać jak nazwy w kodzie przekładają się na nazwy w artykule. Wtedy zamiast czytać kod, mogę przeczytać artykuł, który odpowie na znacznie więcej pytań niż kod, który może być błędny.

Odnośnie punktu 1. sprzeczny z kodem komentarz powinien być traktowany jako błąd. Komentarz często pokazuje intencję autora kodu i pozwala łatwiej odkrywać błędy. Np. jak podczas recenzji zobaczę, że komentarz mówi X, a kod robi Y, to będę miał pytania. Jak zobaczę tylko sam kod, to mogę nie wpaść, że autor myślał, że kod miał robić X, ale mu nie wyszło i robi Y.

Choć oczywiście jeśli da się intencję wyrazić np. w formie asercji albo testu, to będzie to zawsze lepsze niż komentarz. Ale nie zawsze się da i nie zawsze jest na to czas. Komentarz ma też tę zaletę, że może być blisko miejsca, którego dotyczy, a test jest niestety osobno.

Komentarze się przydają też do oznaczania kodu, który na pierwszy rzut oka wydaje się zły, ale jest np. potrzebny w jakimś brzegowym przypadku. Np. w Netty ostatnio natrafiłem na kawałek kodu sprzeczny z rfc dla http. Gdyby nie komentarz, to już bym zgłosił błąd.

1

Tu pomoże tylko strzelba i szpadel, ew. zmiana kolegi bądź pracy.

3
Julian_ napisał(a):

Nowaki potrzebne by było wiadomo kto daną linijkę tak spartolił.

Od tego jest blame.

Uzasadnione komentarze są też takie, które wyjaśniają jakiś hack albo workaround. Oczywiście takich miejsc w kodzie powinno być jak najmniej, ale i tak będą, a skoro będą to powinny być wyjaśnione by znowu kto inny nie wykasował czegoś bo wygląda na błąd albo na niepotrzebny kod.

3
  1. Zmień otoczenie. Umów się na spotkanie z kolegą w kawiarni, zamiast w sali konferencyjnej. Spotkanie w otoczeniu innych ludzi sprawi, że kolega będzie mniej skłonny do agresji.
  2. Naśladuj język ciała kolegi. Jeżeli on się garbi lub kuleje na jedną nogę, to zacznij rozmowę garbiąc się lub kulejąc. To tzw. "efekt kameleona", który sprawia, że zaczynamy lubić osobę, która przypomina nas samych.
  3. Mów szybciej. Mówiąc szybciej dasz koledze mniej czasu na analizę i rzeczowe odparcie argumentów.
  4. Pokaż mu obrazek z oczami. Oczy kojarzą się z kontrolą społeczną, daj koledze wrażenie, że jest obserwowany.
  5. Powiedz mu to pod koniec dnia pracy. Gdy jesteśmy bardziej zmęczeni i rozkojarzeni, to jesteśmy również mniej krytyczni i chętniej zgadzamy się ze zdaniem innych.
  6. Powiedz mu, że zabijesz mu babcię, a następnie zacznij się śmiać. Gdy doświadczamy lęku, a następnie ulgi pozytywniej reagujemy na prośby.
  7. Pogładź go po ramieniu. Kontakt fizyczny może sprawić, że jesteśmy bardziej skłonni do współpracy. Przykładowo gdy zapytasz kobietę o numer, dotykając ją przy tym przypadkowo zwiększasz swoje szanse na jego otrzymanie.
  8. Powiedz mu, że ma prawo się nie zgadzać. Sprawiając wrażenie, że dajesz koledze wolność wyboru, dwukrotnie zwiększasz prawdopodobieństwo, że zgodzi się z tym co mówisz.
1
Julian_ napisał(a):

Jak kolega "głupio gada" to proponuję takie rozwiązanie, na pewno zadziała:

0
Julian_ napisał(a):

Żeby nie było: jest on generalnie mądry i utalentowany, ale nie interesuje się developerką.

przy tym prawdopodobnie jest chory psychicznie
po co ty mu w ogóle chesz cokolwiek tłumaczyć? po prostu nie piszcie tych p----------lonych komentarzy, szlag go trafi i sam się zwolni

6

Panowie, przypominam o kulturze – przede wszystkim @Sceptyczny Dinozaur, bo to nie pierwszy Twój raz, gdy rzucasz wulgaryzmami na lewo i prawo, obskurnie je maskując. Jeśli nie potrafisz wypowiadać się w przyzwoity sposób to idź do Flame i z niego nie wychodź, albo nie wypowiadaj się wcale.

4

Niektórzy programiści to się strasznie o pierdoły lubią kłócić. Komentarze vs brak komentarzy. Taby vs spacje. Klamerka w tej samej linii vs w osobnej.

Kolega pisze trochę więcej komentarzy? Ok, a w czym to tak naprawdę szkodzi? Kod będzie od tego działał gorzej? Dysk na serwerze Wam się od tego zapełni?

Rozumiem argument, że komentarz może się rozsynchronizować z kodem, ale szczerze jest to argument bardzo naciągany. W całej karierze spotkałem może kilka takich sytuacji i żadna nie spowodowała przestoju dłuższego niż minuta. Widzę zły komentarz, poprawiam i jadę dalej.

Taka sama sytuacja może nastąpić w kodzie bez komentarzy - ktoś może zmienić semantykę, a zapomnieć zmienić nazwę zmiennej / funkcji i też będzie mylić. Kompilator tego nie złapie, a recenzent może przeoczyć.

Argumenty o tym, że kod powinien się sam opisywać, jest teoretycznie słuszny, ale w praktyce widzę, że jest on tylko wymówką dla lenistwa i niepisania komentarzy tam, gdzie powinny być. Większość kodu pisanego nawet przez dobrych programistów nie jest wcale czytelna. A w każdym razie z dobrym komentarzem jest dużo bardziej czytelna niż bez.

Liczba sytuacji, kiedy próbowałem zrozumieć czyjś kod i szło opornie, bo kod był niezbyt dobry, a komentarzy i dokumentacji właśnie brakowało, jest istotnie większa od liczby sytuacji, gdzie komentarz mylił.

0
Krolik napisał(a):

Większość kodu pisanego nawet przez dobrych programistów nie jest wcale czytelna.

Może zatem nie są wcale dobrzy?

A w każdym razie z dobrym komentarzem jest dużo bardziej czytelna niż bez.

A który komentarz z pierwszego posta jest dobry? Ten, który udaje system kontroli wersji, czy ten, który mówi, że funkcja sum2Vects dodaje dwa wektory?

0

Liczba sytuacji, kiedy próbowałem zrozumieć czyjś kod i szło opornie, bo kod był niezbyt dobry, a komentarzy i dokumentacji właśnie brakowało

jeśli kod jest niezbyt dobry, to i komentarz niewiele pomoże.

chociaż w sumie... jeśli miałbym pracować z jakimś spaghetti kodem, to jednak wolałbym, żeby była dobra dokumentacja. Rzecz w tym, że to się ze sobą zwykle wiąże i jeśli kod jest słaby to i dokumentacja zwykle jest słaba (bo jeśli "nie ma czasu" pisać dobrego kodu, to tak samo "nie będzie czasu" pisać dobrej dokumentacji).

Natomiast nie każda pierdółka wstawiona do kodu jako niby dokumentacja, jest w rzeczywistości faktyczną przydatną dokumentacją (ja np. adnotacje nad funkcjami z nazwami parametrów i co który parametr robi, zwykle ignoruję, bo i tak to widzę w kodzie. Natomiast często brakuje mi ogólnej dokumentacji z lotu ptaka, albo wytłumaczenie pewnych WTFów, a nie komentarzy dla samych komentarzy).

0

http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode
http://blog.cleancoder.com/uncle-bob/2017/02/23/NecessaryComments.html

W skrócie:

  • komentarze często są pisane aby usprawieliwić błędnie napisany kod (złe nazwy, architektura, metody które robią za dużo, spaghetti)
  • komentarze uwalniają nas od poprawnego nazewnictwa, klasa BSMKRW nic nam nie mówi, więc dodajemy komentarz na górze klasy "Bardzo Skomplikowany Manager Który Robi Wszystko"
  • czasami musimy umieścić komentarz jeżeli nie możemy uproscić metody która np. wykonuje bardzo skomplikowany algorytm
4
somekind napisał(a):
Krolik napisał(a):

Większość kodu pisanego nawet przez dobrych programistów nie jest wcale czytelna.

Może zatem nie są wcale dobrzy?

Większość programistów nie jest dobra.
Ale nawet dobry kod trudno zrozumieć bez dokumentacji, jeśli jest go 3 miliony linii, a masz znaleźć błąd na jutro.

A w każdym razie z dobrym komentarzem jest dużo bardziej czytelna niż bez.

A który komentarz z pierwszego posta jest dobry? Ten, który udaje system kontroli wersji, czy ten, który mówi, że funkcja sum2Vects dodaje dwa wektory?

Pisałem ogólnie. Ale jak już przy tym jesteśmy, to komentarz z numerem błędu, który naprawia dany kod jest dobry. System kontroli wersji zawiera znacznie więcej informacji i znacznie więcej czasu zajmie wyszukanie z niego linku do błędu, bo trzeba jeszcze odszukać odpowiedni commit i przekopać się przez opisy. Natomiast komentarz od razu pokazuje, gdzie szukać.

Komentarz, który mówi, że funkcja dodaje dwa wektory, jest neutralny - nic nie wnosi, ale i nie przeszkadza. A właściwie to nawet może być użyteczny. Wpiszę w wyszukiwarkę "jak dodać dwa wektory" i mam szansę to znaleźć - właśnie po komentarzu.

chociaż w sumie... jeśli miałbym pracować z jakimś spaghetti kodem, to jednak wolałbym, żeby była dobra dokumentacja. Rzecz w tym, że to się ze sobą zwykle wiąże i jeśli kod jest słaby to i dokumentacja zwykle jest słaba (bo jeśli "nie ma czasu" pisać dobrego kodu, to tak samo "nie będzie czasu" pisać dobrej dokumentacji).

Brak dokumentacji jest gorszy niż słaba dokumentacja. Jeśli kod jest słaby i słaba dokumentacja, to jednak dokumentacja daje cień szansy, że autor bełkotliwie zawarł w niej jakieś informacje uzupełniające kod. BDORW z komentarzem Bardzo Duży Obiekt Robiący Wszystko nie jest ładne, ale jednak czytelniejsze niż samo BDORW.

komentarze często są pisane aby usprawieliwić błędnie napisany kod (złe nazwy, architektura, metody które robią za dużo, spaghetti)
komentarze uwalniają nas od poprawnego nazewnictwa

Naiwnym jest sądzić, że piętnowanie pisania komentarzy poprawi kod. Nie poprawi. Słabi programiści będą pisać słaby kod bez komentarzy i tyle.

To tak jakby zabronić testów i liczyć na to, że programiści zaczną pisać bezbłędny kod, bo nie mogą już polegać na testach, a muszą na sobie.

2

Przykład znaleziony dzisiaj:

plot(f, -4, 3) # plot f over [-4,4]

1 użytkowników online, w tym zalogowanych: 0, gości: 1