Dorzuce jeszcze troche odnosnie pkt 2 z powyszego posta ("ze swojego doświadczenia") ze jesli dodajemy do kodu komentarze/docstringi to teoretycznie "powinny" być one ogólne/generyczne w tym sensie żeby w komentarzu unikać hardkodowania konkretnych nazw zmiennych/klas/metod (jesli to mozliwe).
czyli np: zmiana nazwy metody/zmiennej itp na ogół nie powinna wymuszac koniecznosci zmiany docstring-a - spotkałem się z przypadkiem gdzie ludzie w docstringach pewnych metod używali nazw własnych czy nazw zmiennych innych metod. Nie muszę mówić że potem przy zmianie czegoś należało zmienić docstringi w wielu metodach. Oczywiście na review był "Cerber" który tego pilnował ale było to "słabe" i może pomysł czy idea nie były złe ale mało pragmatyczne.
Ów pragmatyzm wynika z tego że: developerzy sa leniwi(powinni być :P) | developerzy nie chca /nie lubia/ zapominaja edytowac docstringi po zmianach i tak robi sie balagan opisany w pkt 2
(troche bzdurny przyklad ale wlasnie mi przyszedl do glowy)
Chcemy zainstalowac klucz publiczny na remote serwerze (wczesniej wygenerowalismy klucze lokalnie ofc) zeby smigac po ssh.
Ktos napisal mniej wiecej cos takiego (pseudokod).
def send_public_key_from_local_path_to_remote_server(local_path,
remote_user_login, remote_user_password, remote_server):
"""Copy locally generated ssh keys from local_path to remote_server with
using remote_user_login account. """
cmd = "ssh-copy-id -i {} {}@{}".format(local_path, remote_user_login ,remote_server)
run_ssh(cmd)
...
Ktos bardziej leniwy od poprzednika w to zajrzal i zlapal sie za glowe i mysli omg "Co za pracowity Janusz":
I zabral sie za zmiany i zmienił nazwe funkcji i nazwy zmiennych ogolnie uznal ze lepiej haslo i login
wysylac np: jako jeden obiekty 'credentials' i nawet zmienil to w docstringu ->
extra uznal ze w zasadzie wszyscy z reguly uzywaja kluczy ze sciezki domyslnej wiec mozna
miec metoda z mniejsza ilosc zmiennych.
Ale nieborak zapomnial zmienic nazw wszystkich zmiennych w docstringach zagapil sie jakos mu umknelo wystawil MR
poszlo do review ;D
def send_public_key(path=None, credentials, server):
"""Copy locally generated ssh keys from local_path to remote_server
with using credentials. """
path = '/home/.ssh/id_rsa.pub' or path
cmd = "ssh-copy-id -i {} {}@{}".format(path, credentials.login ,server)
run_ssh(cmd)
...
Za review i mergowanie odpowiedzialny jest junior bo Lead jest w Teamie jeden
i akurat jest na urlopie i wroci za 3 tygodnie a wiadomo robota musi iść do przodu.
I BANG "Merge" bez zadnych zmian.
Po 3 tygodniach wraca Lead i przeglada Merge i trafia na ten temat i widzi rozjazd a ze Lead to pewnie sie zna to sobie mysli tak:
Jest rozjazd w docstringach nie zgadzaja sie nazwy zmiennych z rzeczywistym:
I robi TAK:
def send_public_key(path=None, credentials, server):
"""Copy locally generated ssh keys to remote server. """
path = '/home/.ssh/id_rsa.pub' or path
cmd = "ssh-copy-id -i {} {}@{}".format(path, credentials.login ,server)
run_ssh(cmd)
...
No i sobie mysli bedzie git teraz jest generycznie i nie ma bledow i rozjazdu... no ale mysli myśli myśli
Nazwa funkcji w sumie jest OK i mowi co robi wiec docstring nic nie wnosi.
Każdy wie jak dziala "ssh-copy-id" na Linuxie i po co to pisać.
Sobie mysli Jestę Lead Developerę i zrobię CIACH
i dopiszę unit testy !
def send_public_key(path=None, credentials, server):
path = '/home/.ssh/id_rsa.pub' or path
cmd = "ssh-copy-id -i {} {}@{}".format(path, credentials.login ,server)
run_ssh(cmd)
...
Przyklad wziety 'z czapy' i mega uproszczony (trzebaby poprawic) ale podobny mechanizm działania widzialem już wiele razy na dużo większą skalę i w dużo bardziej "zaawansowanych" przykładach gdzie ludzie wykonywali nikomu nie potrzebną pracę w komentarzach - nikt tego nie czyta calosc tylko zaciemnia i doklada robote na 'maintenance'. Lepiej poswiecic czas na dobre zmienne nazwy czy dopracowanie unit-testow albo dopisanie kilku scenariuszy testow integracyjnych zamiast tracic czas i zapal na docstringi.