Twórz komentarze w języku Python we właściwy sposób

Komentarze to notatki, które programiści umieszczają w swoim kodzie, aby wyjaśnić, co ten kod ma robić. Kompilatory lub interpretery, które przekształcają kod w działanie, ignorują komentarze, ale mogą być niezbędne do zarządzania projektami oprogramowania.

Komentarze pomagają wyjaśnić twój kod Pythona innym programistom i mogą przypomnieć ci, dlaczego dokonałeś wyborów, których dokonałeś. Komentarze ułatwiają debugowanie i poprawianie kodu, pomagając przyszłym programistom zrozumieć wybory projektowe stojące za oprogramowaniem.

Chociaż komentarze są przeznaczone głównie dla programistów, pisanie efektywnych komentarzy może również pomóc w stworzeniu doskonałej dokumentacji dla użytkowników kodu. Z pomocą generatorów dokumentów, takich jak projekty Sphinx for Python, komentarze w kodzie mogą stanowić treść dokumentacji.

Zajrzyjmy pod maskę komentowania w Pythonie.

Komentarze w Pythonie

Według przewodnika stylistycznego Python PEP 8, podczas pisania komentarzy należy pamiętać o kilku rzeczach:

• Komentarze powinny być zawsze pełnymi i zwięzłymi zdaniami.
• Lepiej nie mieć żadnego komentarza, niż taki, który jest trudny do zrozumienia lub niedokładny.
• Komentarze powinny być regularnie aktualizowane, aby odzwierciedlały zmiany w kodzie.
• Zbyt wiele komentarzy może rozpraszać i obniżać jakość kodu. Komentarze nie są potrzebne, gdy cel kodu jest oczywisty.

W Pythonie linia jest deklarowana jako komentarz, gdy zaczyna się od symbolu # . Kiedy interpreter Pythona napotka # w twoim kodzie, ignoruje wszystko po tym symbolu i nie generuje żadnego błędu. Istnieją dwa sposoby deklarowania komentarzy jednowierszowych: komentarze wbudowane i komentarze blokowe.

Komentarze w tekście

Komentarze wbudowane zawierają krótkie opisy zmiennych i prostych operacji i są zapisywane w tym samym wierszu, co instrukcja kodu:

 border = x + 10 # Make offset of 10px

Komentarz wyjaśnia funkcję kodu w tej samej instrukcji co kod.

Zablokuj komentarze

Komentarze blokowe służą do opisywania złożonej logiki w kodzie. Komentarze blokowe w Pythonie są zbudowane podobnie do komentarzy wbudowanych — jedyną różnicą jest to, że komentarze blokowe są zapisywane w osobnej linii:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

Pamiętaj, że podczas korzystania z komentarzy blokowych komentarze są zapisywane nad kodem, który wyjaśniają. Przewodnik stylistyczny Pythona PEP8 mówi, że wiersz kodu nie powinien zawierać więcej niż siedemdziesiąt dziewięć znaków, a komentarze wbudowane często wypychają wiersze o tej długości. Dlatego komentarze blokowe są zapisywane w celu opisania kodu w osobnych wierszach.

Komentarze wielowierszowe

Python natywnie nie obsługuje komentarzy wielowierszowych, co oznacza, że ​​nie ma specjalnych przepisów dotyczących ich definiowania. Mimo to często używane są komentarze obejmujące wiele wierszy.

Możesz utworzyć komentarz wielowierszowy z kilku komentarzy jednowierszowych, poprzedzając każdy wiersz znakiem # :

 # interpreter # ignores # these lines

Możesz także użyć składni ciągów wielowierszowych. W Pythonie możesz definiować ciągi wielowierszowe, umieszczając je w """ , potrójnych podwójnych cudzysłowach lub ''' , potrójnych pojedynczych cudzysłowach:

 print("Multi-Line Comment") """ This String is Multi line """

W powyższym kodzie ciąg wielowierszowy nie jest przypisany do zmiennej, co sprawia, że ​​ciąg działa jak komentarz. W czasie wykonywania Python ignoruje łańcuch znaków i nie jest on dołączany do kodu bajtowego. Wykonanie powyższego kodu daje następujący wynik:

 Multi-Line Comment

Komentarze specjalne

Oprócz zwiększania czytelności kodu, komentarze służą w Pythonie do specjalnych celów, takich jak planowanie przyszłych dodanych kodów i generowanie dokumentacji.

Komentarze w języku Python Docstring

W Pythonie ciągi dokumentów to wielowierszowe komentarze, które wyjaśniają, jak używać danej funkcji lub klasy. Dokumentacja twojego kodu jest ulepszana przez tworzenie wysokiej jakości dokumentów. Podczas pracy z funkcją lub klasą i korzystania z wbudowanej funkcji help(obj) docstringi mogą być pomocne w przedstawieniu przeglądu obiektu.

Python PEP 257 zapewnia standardową metodę deklarowania docstringów w Pythonie, pokazaną poniżej:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

W powyższym kodzie dokumentacja zawierała szczegółowe informacje na temat działania powiązanej funkcji. Dzięki generatorom dokumentacji, takim jak Sphinx, ten ciąg dokumentów może być wykorzystany do przedstawienia użytkownikom Twojego projektu przeglądu sposobu korzystania z tej metody.

Docstring zdefiniowany tuż pod sygnaturą funkcji lub klasy można również zwrócić za pomocą wbudowanej funkcji help() . Funkcja help() przyjmuje nazwę obiektu lub funkcji jako argument i zwraca docstringi funkcji jako dane wyjściowe. W powyższym przykładzie można wywołać help(get_person) w celu ujawnienia ciągów dokumentów powiązanych z funkcją get_person . Jeśli uruchomisz powyższy kod w interaktywnej powłoce przy użyciu flagi -i , zobaczysz, jak ten ciąg dokumentów zostanie przeanalizowany przez Pythona. Uruchom powyższy kod, wpisując python -i file.py .

Wywołanie funkcji help(get_person) zwraca ciąg dokumentów dla Twojej funkcji. Dane wyjściowe zawierają get_person(name, age, d=False) , która jest sygnaturą funkcji, którą Python dodaje automatycznie.

get_person.__ doc__ można również użyć do programowego pobierania i modyfikowania ciągów dokumentów. Po dodaniu „Some more new information” w powyższym przykładzie pojawia się ona w drugim wywołaniu help(get_person) . Mimo to jest mało prawdopodobne, że będziesz musiał dynamicznie zmieniać dokumenty w czasie wykonywania w ten sposób.

Komentarze do zrobienia

Podczas pisania kodu zdarzają się sytuacje, w których chcesz wyróżnić pewne wiersze lub całe bloki w celu ulepszenia. Te zadania są oznaczane przez komentarze TODO. Komentarze TODO przydają się, gdy planujesz aktualizacje lub zmiany w swoim kodzie lub jeśli chcesz poinformować użytkowników lub współpracowników projektu, że określone sekcje kodu pliku pozostają do napisania.

Komentarze TODO nie powinny być zapisywane jako pseudokod — mają po prostu krótko wyjaśnić funkcję jeszcze nienapisanego kodu.

Komentarze TODO i jednowierszowe komentarze blokowe są bardzo podobne, a jedyną różnicą między nimi jest to, że komentarze TODO muszą zaczynać się od przedrostka TODO:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

Należy zauważyć, że chociaż wiele środowisk IDE może podświetlać te komentarze dla programisty, interpreter Pythona nie widzi komentarzy TODO w żaden inny sposób niż komentarze blokowe.

Najlepsze praktyki podczas pisania komentarzy w języku Python

Istnieje szereg najlepszych praktyk, których należy przestrzegać podczas pisania komentarzy, aby zapewnić niezawodność i jakość. Poniżej znajduje się kilka wskazówek dotyczących pisania wysokiej jakości komentarzy w Pythonie.

Unikaj oczywistości

Komentarze, które stwierdzają oczywistość, nie dodają żadnej wartości do twojego kodu i należy ich unikać. Na przykład:

 x = x + 4 # increase x by 4

Ten komentarz nie jest przydatny, ponieważ po prostu określa, co robi kod, bez wyjaśniania, dlaczego należy to zrobić. Komentarze powinny wyjaśniać „dlaczego”, a nie „co” kodu, który opisują.

Przepisany w bardziej użyteczny sposób, powyższy przykład może wyglądać tak:

 x = x + 4 # increase the border width

Postaraj się, aby komentarze Pythona były krótkie i treściwe

Postaraj się, aby Twoje komentarze były krótkie i zrozumiałe. Powinny być napisane standardową prozą, a nie pseudokodem, i powinny zastąpić konieczność czytania rzeczywistego kodu, aby uzyskać ogólny przegląd tego, co robi. Zbyt wiele szczegółów lub złożone komentarze nie ułatwiają pracy programisty. Na przykład:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Powyższy komentarz zawiera więcej informacji, niż jest to konieczne dla czytelnika. Zamiast określać podstawową logikę, komentarze powinny zawierać ogólne podsumowanie kodu. Ten komentarz można przepisać jako:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Ostrożnie używaj identyfikatorów

Identyfikatorów należy używać ostrożnie w komentarzach. Zmiana nazw identyfikatorów lub przypadków może wprowadzić czytelnika w błąd. Przykład:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

Powyższy komentarz wspomina o class i argument , których nie ma w kodzie. Ten komentarz można przepisać jako:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

SUCHE i MOKRE

Kiedy piszesz kod, chcesz przestrzegać zasady DRY (nie powtarzaj się) i unikać WET (pisz wszystko dwa razy).

Dotyczy to również komentarzy. Unikaj używania wielu instrukcji do opisywania swojego kodu i spróbuj scalić komentarze wyjaśniające ten sam kod w jednym komentarzu. Jednak ważne jest, aby zachować ostrożność podczas łączenia komentarzy: nieostrożne łączenie wielu komentarzy może skutkować obszernym komentarzem, który narusza wytyczne dotyczące stylu i jest trudny do zrozumienia dla czytelnika.

Pamiętaj, że komentarze powinny skracać czas czytania kodu.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

W powyższym kodzie komentarze są niepotrzebnie pofragmentowane i można je połączyć w jeden komentarz:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

Spójne wcięcie

Upewnij się, że komentarze mają wcięcie na tym samym poziomie, co kod, który opisują. Gdy ich nie ma, śledzenie ich może być trudne.

Na przykład ten komentarz nie jest odpowiednio wcięty lub umieszczony:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

Można to przepisać w następujący sposób:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

Streszczenie

Komentarze są ważnym elementem pisania zrozumiałego kodu. Inwestycja, jaką poczynisz, pisząc komentarz, z pewnością docenią Twoi przyszli ja — lub inni programiści, którzy będą musieli pracować nad Twoją bazą kodu. Komentowanie pozwala również uzyskać głębszy wgląd w kod.

W tym samouczku dowiesz się więcej o komentarzach w Pythonie, w tym o różnych typach komentarzy Pythona, kiedy używać każdego z nich oraz o najlepszych praktykach, których należy przestrzegać podczas ich tworzenia.

Pisanie dobrych komentarzy to umiejętność, którą należy studiować i rozwijać. Aby poćwiczyć pisanie komentarzy, rozważ cofnięcie się i dodanie komentarzy do niektórych poprzednich projektów. Aby uzyskać inspirację i zobaczyć najlepsze praktyki w działaniu, zapoznaj się z dobrze udokumentowanymi projektami Pythona w serwisie GitHub.

Kiedy będziesz gotowy do uruchomienia własnych projektów w języku Python, platforma Application Hosting firmy Kinsta może w ciągu kilku sekund przenieść Twój kod z GitHub do chmury.