Wprowadzenie do komentarzy i czytelności kodu

Komentarze służą do wyjaśniania kodu i zwiększania jego czytelności. Interpreter języka Python ignoruje komentarze, więc nie wpływają one na wykonanie programu.

W tej lekcji dowiedzą się Państwo, jak używać komentarzy i pisać przejrzysty, czytelny kod.

Komentarze jednowierszowe

Komentarze jednowierszowe zaczynają się od znaku #. Wszystko, co znajduje się za znakiem # w danym wierszu, jest ignorowane przez Pythona. Na przykład:

# This is a single-line comment
print("Hello, World!")

Komentarze wielowierszowe

Komentarze wielowierszowe można zapisywać za pomocą potrójnych cudzysłowów (''' lub """). Na przykład:

"""
This is a multi-line comment.
It spans multiple lines.
"""
print("Hello, World!")

Dlaczego używać komentarzy?

Komentarze pomagają:

• wyjaśniać złożony kod;
• ułatwiać zrozumienie kodu innym osobom oraz Państwa przyszłym wersjom;
• debugować kod i rozwiązywać problemy.

Należy pamiętać, że komentarze są przeznaczone dla ludzi, a nie dla maszyny!

Dobre praktyki komentowania

Oto kilka wskazówek dotyczących pisania dobrych komentarzy:

• Niech komentarze będą zwięzłe i znaczące.
• Należy unikać oczywistych komentarzy, takich jak # Increment x by 1 dla kodu x = x + 1.
• Należy używać komentarzy do wyjaśniania, dlaczego kod został napisany w określony sposób.

Zwiększanie czytelności kodu

Czytelny kod łatwiej utrzymywać i debugować. Oto kilka wskazówek:

• Należy używać opisowych nazw zmiennych i funkcji.
• Należy unikać zbyt długich wierszy kodu.
• Należy organizować kod w sekcje za pomocą komentarzy.

Zakomentowywanie kodu

Można używać komentarzy do tymczasowego wyłączania kodu na potrzeby debugowania. Na przykład:

# print("This line is commented out and won’t run.")
print("This line will run.")

Przykład: dokumentowanie funkcji

Można używać komentarzy do dokumentowania funkcji i wyjaśniania ich przeznaczenia:

def greet(name):
    # This function greets the user by their name.
    print("Hello,", name)

greet("Alice")

Czego się Państwo nauczyli?

W tej lekcji dowiedzieli się Państwo:

• jak pisać komentarze jedno- i wielowierszowe w języku Python;
• jakie znaczenie mają komentarze dla czytelności i łatwości utrzymania kodu;
• jakie są najlepsze praktyki pisania komentarzy i zwiększania czytelności kodu.

Doskonale! Przejdźmy do następnego tematu.