Pisanie dobrych komentarzy w Pythonie umożliwi innym programistom i testerom łatwe przeczytanie i zrozumienie Twojego kodu.
Czysty kod ze spójną składnią, opisowym nazewnictwem zmiennych i wcięciami jest jak w pierwszej książce, łatwiejszy do zrozumienia i utrzymania.
Ponadto obecnie rzadziej zdarza się, aby pojedyncza osoba pisała pełny kod całej aplikacji lub oprogramowania; raczej zespół lub grupa ludzi będzie pracować nad tym samym celem. W tym przypadku czysty i czytelny kod sprawia, że współpraca jest prostsza i wydajniejsza.
Programiści i testerzy zawsze dążą do wdrożenia oprogramowania wolnego od błędów w środowisku produkcyjnym. Pisanie czystego i czytelnego kodu przyspiesza ten proces, czyniąc debugowanie prostszym i dokładniejszym. Chociaż znajdziesz pewne błędy w produkcji, czystszy kod jest łatwiejszy do aktualizacji.
Co ważniejsze, czysty i czytelny kod żyje dłużej, ponieważ kod pozostaje świeży wraz z upływem czasu.
Wreszcie, aby stworzyć długotrwałe oprogramowanie, kluczowy jest czysty i czytelny kod. Pytanie jednak brzmi, jak dokładnie to osiągnąć? Cóż, jedną z metod jest użycie komentarzy.
Czy nie jest to frustrujące, gdy napisałeś cały kod dla złożonej logiki, ale następnego dnia nie możesz kontynuować od miejsca, w którym przerwałeś? Nie dzieje się tak, gdy piszesz komentarze.
Komentarze są ludzkim językiem wyjaśniającym, co robi kod źródłowy. Można je napisać w dowolnym języku, najlepiej po angielsku, gdyż jest to język globalny.
Zatem za każdym razem, gdy po kilku dniach lub nawet latach wrócisz do kodu źródłowego, komentarze wyjaśnią ci to, co kiedyś napisałeś.
Pomagają także innym programistom w łatwym zrozumieniu Twojego kodu. Dlatego kod napisany z komentarzami pozostaje na zawsze, nawet pod nieobecność jego autora.
Co więcej, dość powszechne są konflikty podczas pracy z różnymi językami programowania, zwłaszcza gdy pracujesz w zespole. I tu z pomocą przychodzą komentarze. Chociaż nie znasz języka programowania kodu źródłowego napisanego przez Twojego kolegę z zespołu, komentarze pomogą Ci zrozumieć logikę stojącą za nim.
Dokumentacja kodu to bardziej kompleksowy sposób utrzymywania kodu źródłowego i pozwala Twojemu zespołowi na bezproblemową współpracę. Zawiera wszystko o kodzie, takie jak projekt, funkcjonalność, architektura, komponenty itp.,
Komentarze przyczyniają się nawet do dokumentacji tego kodu. Dobrze napisane komentarze można bezpośrednio uwzględnić w dokumentacji kodu, dzięki czemu programiści nie tylko dowiedzą się, co i dlaczego, ale także jak wykonać kod.
- Komentarze nie tylko odczytują kod, ale także pomagają zrozumieć intencje programisty kryjące się za każdą linijką. Jeśli więc w przyszłości znajdziesz jakiś błąd, będziesz wiedział, gdzie dokładnie dokonać aktualizacji kodu.
- Możesz pisać komentarze jako akapity dla całego kodu lub poszczególnych linii wyjaśniających, co robi każdy blok kodu. W ten sposób pozwalają Tobie i innym programistom dobrze zrozumieć kod, zwiększając czytelność.
- Komentarze mogą dzielić kod na logiczne sekcje, ułatwiając nawigację po kodzie.
- Powinieneś dołączyć komentarze szczegółowo opisujące oczekiwane dane wejściowe, wyniki i przypadki użycia, aby tester mógł odczytać Twój kod.
- Wreszcie, umieszczanie dobrze napisanych komentarzy w dokumentacji poprawia ogólną czytelność dokumentacji kodu.
Komentarze w Pythonie zaczynają się od symbolu hash (#). Tak więc, jeśli zaczynasz linię od hasha (#), wszystko, co jest napisane w tej linii, jest traktowane jako komentarz.
Po uruchomieniu kodu kompilator ignoruje linię zaczynającą się od hasha (#), jakby w ogóle nie istniała. Jednakże komentarze pozostają widoczne w kodzie źródłowym, aby spełniały swoją funkcję.
Istnieją trzy główne typy.
To są te, które widzieliście powyżej. Zaczynają się od symbolu hash (#). Zasadniczo linia rozpoczynająca się od symbolu hash (#) jest przeznaczona na komentarz. Nazywa się to zatem komentarzem jednowierszowym i można go wpisać tylko w jednym wierszu, zaczynając od znaku hash (#).
Oto jak możesz pisać komentarze jednowierszowe
# This is single line comment.
Technicznie rzecz biorąc, Python nie obsługuje komentarzy wielowierszowych, ale istnieją sposoby, aby to osiągnąć w Pythonie.
Możesz także używać skrótu (#) do pisania komentarzy wielowierszowych. Każda linia, którą napiszesz, powinna zaczynać się od symbolu krzyżyka (#).
# This is the first comment. # This is second comment. # This is the last comment.
Spis treści:
#3. Dokumentacja Pythona
Popularnym sposobem pisania komentarzy wielowierszowych jest użycie literałów łańcuchowych – „””….””. Kiedy napiszesz coś pomiędzy potrójnymi cudzysłowami, kompilator Pythona ignoruje te linie i wykonuje pozostałą część pliku.
Komentarze te nazywane są dokumentami, jeśli są zapisywane bezpośrednio po funkcjach, modułach i klasach.
Oto składnia, aby to zrobić
""" Multi-line comments using docstrings in Python. """
Pisanie jasnych i szczegółowych komentarzy poprawia czytelność i konserwację kodu. Oto najlepsze praktyki dotyczące jasnego komentowania w Pythonie.
Komentarze nie powinny po prostu opisywać działania kodu, powinny raczej odzwierciedlać cel i intencję stojącą za każdą linijką.
Usuń nieaktualne komentarze i pamiętaj o ich aktualizacji za każdym razem, gdy modyfikujesz kod.
Zamiast długich historii pisz krótkie i rzeczowe komentarze.
Bad example: The function takes a,b as input, calculates a + b, and returns the value. Good example: The function returns the sum of a and b.
Używanie znaczących i opisowych nazw zmiennych i nazw funkcji może wyeliminować zbędne komentarze.
Najpierw kod? Albo najpierw skomentować? Komentowanie przed kodowaniem jest najlepszą praktyką; to znaczy napisz swoje komentarze, a następnie odpowiedni kod. W ten sposób możesz najpierw pomyśleć o logice, a następnie przekonwertować ją na kod.
# Returns true if the cnt is less than 1. return cnt < 1
Używaj spójnego formatu komentowania, takiego jak odstępy, wcięcia, rodzaj komentarzy itp., dla całego kodu. Będzie to mniej zagmatwane i bardziej uporządkowane dla czytelników.
Użyj dokumentów do wyjaśnienia funkcji i klas w Pythonie, jak pokazano w poniższym przykładzie.
def add_num(a,b):
""" this function returns the sum of a and b """
sum = a+b
return sum
Unikaj niepotrzebnych komentarzy w kodzie. Na przykład następujący wiersz kodu nie wymaga komentarza, aby go zrozumieć.
ans = 42
#1. Edytor kodu Visual Studio
Edytor kodu Visual Studio to najlepsze IDE stworzone przez Microsoft dla kompletnego środowiska programistycznego. Dzięki natywnej obsłudze Node.js i JavaScript narzędzie bezproblemowo obsługuje także wiele innych języków programowania.
To wysoce konfigurowalne narzędzie ma różne rozszerzenia dla różnych funkcjonalności. „Lepsze komentarze” to jedno z takich rozszerzeń, które pozwala tworzyć komentarze przyjazne dla człowieka.
Możesz kategoryzować swoje komentarze według alertów, zapytań, najważniejszych informacji itp., aby ułatwić nawigację.
Kod VS obsługuje edycję wielu kursorów, dzięki czemu możesz komentować lub edytować wiele linii jednocześnie.
Ten edytor jest dostępny na wszystkich głównych platformach, takich jak Mac, Windows i Linux.
#2. Wzniosły tekst
Wzniosły tekst to doskonały edytor do dużych projektów i wymagającego kodowania. Edytor znany jest z szybkości, dostosowywania i skrótów.
Zaawansowana funkcja podświetlania składni narzędzia pomaga łatwo odróżnić kod od komentarzy.
Podobnie jak kod VS, tekst Sublime obsługuje również edycję wielu kursorów w celu jednoczesnego komentowania wielu linii.
Dzięki funkcji autouzupełniania. Nie musisz ręcznie powtarzać linii kodu; ta funkcja automatycznie uzupełnia kod w oparciu o wzorce, pomagając w szybszym kodowaniu.
Co więcej, dostępna w narzędziu funkcja „Goto Everything” umożliwia płynne przełączanie pomiędzy funkcjami i plikami projektu.
#3. Notatnik++
Nodepad++ to popularny i prosty edytor tekstu napisany w C++ i obsługujący wiele języków programowania. Nie wygląda na nowoczesny edytor taki jak VS Code czy Sublime Text; jego interfejs jest bardzo prosty i wygląda na to, że robi to, co powinien.
Nodepad++ oferuje wiele standardowych skrótów umożliwiających efektywne komentowanie. Możesz także dostosować klawiaturę skrótów, aby spersonalizować sposób komentowania.
Funkcja mapy dokumentu pokazuje przegląd struktury projektu, umożliwiając płynną nawigację po plikach, folderach i kodzie.
#4. Krzepa
Krzepa IDE zapewnia szybsze tworzenie i wykonywanie kodu. Wszystko i wszystko można zrobić w tym edytorze za pomocą skrótów klawiaturowych, więc powinieneś włożyć sporo wysiłku w jego opanowanie.
Ten edytor oparty na klawiaturze oferuje także wiele funkcji komentowania za pomocą skrótów klawiaturowych. Posiada zaawansowane funkcje i polecenia umożliwiające efektywną nawigację po komentarzach.
To lekkie oprogramowanie może obsługiwać ogromne pliki i setki języków programowania. Kto nienawidzi darmowych rzeczy? Podobnie jak wszyscy redaktorzy na liście, Vim jest również całkowicie darmowy i ma otwarte oprogramowanie.
Jest natywny dla systemów macOS i Linux i można go pobrać w systemie Windows.
#5. PyCharm
PyCharm to potężne IDE zaprojektowane specjalnie do programowania w języku Python. Chociaż obsługuje wiele innych języków programowania, najlepiej działa w Pythonie. Posiada uzupełnianie kodu, podświetlanie składni i funkcje debugowania dostosowane do języka Python.
Co więcej, sprawia, że komentowanie w Pythonie jest znacznie wydajniejsze. Zawiera funkcje nawigacyjne ułatwiające przechodzenie do konkretnych komentarzy.
Uzyskaj różne szablony komentarzy i wydajnie twórz niestandardowe szablony komentarzy w Pycharm.
Ponadto narzędzia refaktoryzacyjne edytora pozwalają łatwo aktualizować lub poprawiać komentarze.
Wniosek
Przestrzeganie standardów kodu jest konieczne w całym procesie tworzenia kodu i obowiązkowe w przypadku pisania kodu gotowego do produkcji, ponieważ kod powinien być czytelny dla wszystkich innych programistów i testerów.
Ważną praktyką tworzenia czytelnego kodu jest pisanie komentarzy. Komentarze są dostępne w prawie wszystkich językach programowania. Jednak dzięki temu artykułowi powinieneś już wiedzieć, jak pisać komentarze w języku Python, jakie są ich typy i najlepsze praktyki, których należy przestrzegać podczas pisania komentarzy.
Poniżej wymieniono również najlepsze edytory kodu, które pomagają w zarządzaniu komentarzami.