Komentarze w kodzie

[rwrzesien]

Widzę że niektóry kwestie dotyczące komentowanie kodu się powtarzają, dlatego proponuję to opisać i ujednolicić. Moja propozycja:

Nie róbmy komentarzy jako multi-line stringów (oprócz oczywiście funkcji, method i klas).

Dobrze
1.

a = 1

# This is comment before if, it has empty line above to indicate that it start a code block.
if a == 1:
    do_stuff()

a = 1

# This is very very very very very very very very very very very very very very 
# long comment that explains very very very very very very very very very very 
# complicated stuff.
if a == 1:
    do_stuff()

Class A:
    """ Comment explaining sense of existence of this class. """

    def a(self):
        """ This comment is for single line method/function class. """

    def b(self):
        """ 
        This comment is for multi line 
        method/function class. 
        """

Źle
4.

a = 1

""" This comment is treated by interpreter as a string object. """
if a == 1:
    do_stuff()

a = 1

""" This one 
     too. """
if a == 1:
    do_stuff()

Class A:
    # Those

    def a(self):
        # are

    def b(self):
         # bad
         # too.

Umieszczajmy nad linią/blokiem kodu którego dotyczy (nie obok).

Źle
1.

a = 1  # I am short right now but i might grow much longer.

a = 1  # I am short right now but the pylint/mypy comments might appear here too.

a = 1  # I am now referring to single line but this might change someday.

Nech będą to normalnie zdania, z wielkiej litery, zakończone znakiem interpunkcyjnym.

Tu odpuszczę przykłady, ale jeżeli chodzi o przyczynę, po prostu wygląda to bardziej elegancko.

Jeżeli komentarz ma logiczną kontynuację dalej, kończmy go ... i kontynuację zaczynajmy od ....

# If the condition is met code should do this this and that ...
if True:
    a()
    lot()
    of()
    complicated()
    stuff()
# ... otherwise it should do that that and this.
else:
    do()
    other()
    stuff()

[cameel]

Dla mnie brzmi dobrze. Ale mógłbyś to bardziej rozpisać, z przykładami (dobrymi i złymi) tak, żeby każdy wiedział o co chodzi?

[pawelkisielewicz]

Jestem za, zarówno jeżeli chodzi o pomysł Radka, jak i prośbe Kamila. Dobrze byłoby również określić, jakie mniej więcej rzeczy komentujemy - tzn. czy tylko w ostateczności, czy np. wszędzie tam gdzie potencjalnie coś może być niejasne. Chodzi o ujednolienie, aby kod był spójny i żebyśmy wszsycy komentowali mniej więcej tyle samo i w podobny sposób. W książce dot. czystego kodu czytałem, że komentarze to zło i kod powinien tłumaczyć się sam. Nie upieram się przy tym, ale miejsmy wszyscy jeden punkt odniesienia.

I ważne:
komentarzy niestety trzeba pilnować, żeby nie rozjechały się z kodem. Pamiętajmy o tym

[rwrzesien]

W książce dot. czystego kodu czytałem, że komentarze to zło i kod powinien tłumaczyć się sam.

Chodzi nawet o szybkość zrozumienia co robi dany fragment, szybciej przeczytasz i zrozumiesz zdanie które je opisuje niż kilka linijek mniej lub bardziej złożonego kodu (a jeżeli ktoś osiągnął poziom taki, że ma odwrotnie, to szanuję :) ) Generalnie to zdanie może i jest prawdziwe, ale zbyt utopijne żeby dało się je wprowadzić w każdym większym projekcie.

komentarzy niestety trzeba pilnować, żeby nie rozjechały się z kodem. Pamiętajmy o tym

Jak najbardziej pamiętajmy o tym przy review :)

[dybi]

Generalnie to zdanie może i jest prawdziwe, ale zbyt utopijne żeby dało się je wprowadzić w każdym większym projekcie.

@rwrzesien , ośmielam się nie zgodzić ;) Moim zdaniem komentarzy powinniśmy używać tylko wtedy kiedy trzeba. Kod powinien być czytelny i bez nich, a jeśli nie jest, to:

1. Trzebaby przemyśleć czy czasem nie da się inaczej nazwać zmiennych, funkcji, itp
2. Jest to magiczny kod asyncio i bez tygodniowego zakopania się w tutorialach nie wiadomo o co chodzi 😜

To tak pół-żartem, pół-serio. Zgodzę się, że w queue_operations.py dzieje się trochę i możnaby to tam podkomentować ("magia" acyncio...), ale ogólnie to unikałbym (nadmiaru) komentarzy jeszcze z tego względu, że mam obawę, iż może prowokować to hm... "niechlujność" w kodzie, a komentarz będzie pudrem, na zasadzie:
Nie mam pomysłu jak nazwać te zmienne i funkcje... Wiem, nazwę jakoś, ale walnę super komentarz (na 3 linijki!), który to wszystko wyjaśni
Poza tym, pamiętajmy, że komentarze rozciągają wertykalnie kod funkcji/klasy, itp (trudniej objąć całość wzrokiem na jednym monitorze).
I uwaga końcowa - może warto byłoby dwoedzieć się (np. przez audyt) jakie są oczekiwania klienta odnośnie komentarzy? To tylko lużna propozycja.

[rwrzesien]

I uwaga końcowa - może warto byłoby dwoedzieć się (np. przez audyt) jakie są oczekiwania klienta odnośnie komentarzy?

Pytaliśmy dzisiaj na daily, raczej sami nie do końca są pewni i umieścili to w dokumencie jako hasło do dyskusji, ale udało nam się wyciągnąć, że spodziewają się docstringów w dłuższych i mniej oczywistych funkcjach. Ale tworząc to issue nie miałem na myśli audytu a ogólną troskę o czytelność naszego kodu :)

mam obawę, iż może prowokować to hm... "niechlujność" w kodzie

Wydaje mi się, że jesteśmy w stanie wyłapywać to w review, tak jak to robimy obecnie. Myślę że jakość naszego review jako zespołu się już sporo podniosła i takie coś już nie przejdzie (a przynajmniej zostanie wyłapane w większości przypadków). Tym bardziej dłuższy komentarz może spowodować sygnał ostrzegawczy ocho, ten fragment wymagał dodatkowego komentarza, więc trzeba się mu dokładniej przyjrzeć.

Poza tym, pamiętajmy, że komentarze rozciągają wertykalnie kod funkcji/klasy, itp (trudniej objąć całość wzrokiem na jednym monitorze).

Właśnie jak już pewnie zauważyliście dla mnie to nie jest problemem (i ja zauważyłem w drugą stronę, w sensie, że część osób preferuje dzielenie kodu na mniejsze funkcje, nawet jeżeli nie są użyte więcej niż raz). Uważam, że kod pojedynczej funkcji może być długi, o ile po szybkim przeczytaniu pierwszych np. 20 linijek programista dalej wie co się dzieje. A pomocne w tym są właśnie odseparowane komentarzami bloki kodu. Dzielenie na mniejsze funkcje jest moim zdaniem najbardziej przydatne wtedy, kiedy ta funkcja może być użyta więcej niż raz. Inaczej mówiąc, to co w stylu preferowanym przez część osób u nas jest osobną funkcją, dla mnie równie dobrze sprawdza się jako blok kodu opatrzony komentarzem. Ale też nie zamierzam nikogo namawiać do zmiany wypracowanych przez lata nawyków pisania. Może znajdziemy sposób żeby jedno z drugim dobrze połączyć :)

[rwrzesien]

Dodałem przykłady.

[pawelkisielewicz]

Dla mnie ogólnie ok, myślę że nadmiar komentrarzy faktycznie szkodzi, ale jeżeli jakaś część kodu jest mniej jasna warto ją skomentować.

[dybi]

sądzę, że zanim ustalim jak pisać komentarze, najpierw musimy przemyśleć gdzie chcemy je mieć. Jak już wspomniałem wcześniej, jestem zwolennikiem ich mocnego ograniczania (na zasadzie: domyślnie nie piszę komentarza, a nie: domyślnie - piszę). Kod powinien dokumentować się sam. Mocno polecam:
http://www.informit.com/articles/article.aspx?p=1326509
https://www.todaysoftmag.com/article/1120/clean-code-comments-and-formatting
;)

EDIT:
@Code-Poets/all - uprzejmie proszę o zapoznanie się z w/w artykułami

[cameel]

Widzę, że sprawa komentowania jest mocno kontrowersyjna, więc nie damy rady jej rozwiązać tutaj - będziemy musieli to omówić na żywo. W tym issue może skupmy się na oryginalnej propozycji Radka. Czy wszyscy zgadzają się z zaproponowanymi czterema modyfikacjami coding style?

@rwrzesien Ode mnie jeszcze trzy kosmetyczne uwagi:

• Dodaj poświetlatnie kodu w opisie. W tej chwili masz zwykle bloki bez podświetlania
• Masz złe wcięcia na blokach, co powoduje, że wypadają z listy.
  • Masz tak:

    1. Tekst
    <blok>
    2. Tekst
    <blok>
    

  • Powinno być tak:

    1. Tekst
        <blok>
    2. Tekst
        <blok>
    

    To, co ma być wewnątrz elementu listy musi byc wcięte
• Byłoby chyba czytelniej napisać przy każdym numerku z osobna czy pokazuje dobry czy zły przykład.