Komentarze – dokumentowanie kodu

Komentarze to fragmenty kodu, które są ignorowane przez interpreter Pythona. Służą do:

• Wyjaśniania skomplikowanych fragmentów kodu
• Opisywania, co robi dany fragment programu
• Tymczasowego wyłączania kodu bez jego usuwania
• Dodawania notatek dla siebie lub innych programistów
• Dokumentowania funkcji, klas i modułów

Kod jest pisany raz, ale czytany wielokrotnie. Dobre komentarze oszczędzają godziny pracy.

Komentarze jednoliniowe

Komentarze jednoliniowe zaczynają się od znaku # (hash). Wszystko po # do końca linii jest ignorowane.

# To jest komentarz
print("Hello, World!")  # To też jest komentarz

Komentarze wieloliniowe

"""
To jest komentarz wieloliniowy
używający potrójnych cudzysłowów.
Technicznie to string, ale jeśli nie jest przypisany
do zmiennej, Python go ignoruje.
"""
print("Hello")

Potrójne cudzysłowy (docstring) to tak naprawdę stringi, nie komentarze. Jednak gdy nie są przypisane do zmiennej, Python je ignoruje, więc działają jak komentarze.

Pierwszy program – Hello, World!

Utwórz nowy plik o nazwie hello.py w swoim edytorze i wpisz:

print("Hello, World!")

Zapisz plik i uruchom go z terminala lub kliknij przycisk „Run python file” w VSCode:

python hello.py

Na ekranie pojawi się:

Hello, World!

Gratulacje! Właśnie napisałeś swój pierwszy program w Pythonie.

print – to funkcja wbudowana w Pythonie. Służy do wyświetlania danych na ekranie

("Hello, World!") – to argument przekazany do funkcji print. Nawiasy okrągłe oznaczają wywołanie funkcji. Tekst w cudzysłowie to string (łańcuch znaków). Można używać zarówno cudzysłowów podwójnych " jak i pojedynczych '

UWAGA: W Pythonie nie używamy średników na końcu linii

Warianty pierwszego programu

Python jest elastyczny. Oto kilka sposobów wyświetlenia tekstu:

print("Hello, World!")           # Cudzysłowy podwójne
print('Hello, World!')           # Cudzysłowy pojedyncze
print("Hello, 'World'!")         # Kombinacja cudzysłowów
print('Hello, "World"!')         # Odwrotna kombinacja
print("""Hello, World!""")       # Potrójne cudzysłowy
print('''Hello, World!''')       # Potrójne apostrofy

Wszystkie te warianty dają ten sam rezultat. Wybór zależy od kontekstu i osobistych preferencji.

Wyświetlanie tekstu:

print("Witaj w Pythonie!")    #Witaj w Pythonie!
print("To jest druga linia")  #To jest druga linia
print("A to trzecia")         #A to trzecia

Wyświetlanie liczb:

print(42)       #42
print(3.14)     #3.14
print(100 + 50) #150
print(10 * 5)   #50

Liczby nie wymagają cudzysłowów. Python automatycznie rozpoznaje, że to liczby, nie tekst.

Wyświetlanie wielu wartości:

print("Wynik:", 42)                   #Wynik: 42
print("Pi równa się", 3.14)           #Pi równa się 3.14
print("Suma:", 10, "+", 20, "=", 30)  #Suma: 10 + 20 = 30

Wartości oddzielone przecinkami są automatycznie rozdzielane spacją.

Parametry funkcji print()

Funkcja print() ma kilka przydatnych parametrów, które modyfikują jej zachowanie.

print() bez argumentów wyświetla pustą linię.

sep – separator między wartościami

Domyślnie print() oddziela wartości spacją. Możesz to zmienić:

print("Jan", "Kowalski")                    # Domyślnie: spacja
print("Jan", "Kowalski", sep="-")           # Separator: myślnik
print("2024", "01", "15", sep="/")          # Data ze slashami
print("Python", "to", "super", sep="***")   # Własny separator
print("a", "b", "c", sep="")                # Bez separatora

"""wynik
Jan Kowalski
Jan-Kowalski
2024/01/15
Python***to***super
abc"""

end – zakończenie linii

Domyślnie print() kończy się znakiem nowej linii (\n). Możesz to zmienić:

print("To jest pierwsza linia")   #doda \n
print("To jest druga linia")      #doda \n

print("Loading", end="...")       #nie doda \n tylko ...
print("Done!")                    #Loading...Done!

PEP 8 i nowoczesne standardy stylu w Pythonie

PEP 8 to jeden z najważniejszych dokumentów w świecie Pythona. To oficjalny przewodnik stylistyczny, który definiuje, jak powinien wyglądać dobrze napisany kod Pythona. Zrozumienie i stosowanie PEP 8 odróżnia początkującego od profesjonalnego programisty Python.

PEP to skrót od Python Enhancement Proposal (Propozycja Ulepszeń Pythona). To dokumenty opisujące nowe funkcje, procesy lub standardy dla języka Python. https://www.python.org/dev/peps/

„Code is read much more often than it is written” – Kod jest czytany znacznie częściej niż pisany.

Gdy wszyscy programiści przestrzegają tych samych zasad:

• Kod jest bardziej czytelny i zrozumiały
• Łatwiej znaleźć błędy podczas code review
• Nowi programiści szybciej się adaptują do projektu
• Współpraca jest płynniejsza i mniej konfliktowa
• Automatyczne narzędzia mogą łatwiej analizować kod

Kluczowe zasady PEP 8

Główne zasady formatowania 

1. Wcięcia (Indentation)

W Python nie ma nawiasów grupujących bloki kodu – są wcięcia. Jeżeli kod nie będzie odpowiednio ułożony, będą wyskakiwały błędy.

Używaj 4 spacji na poziom wcięcia. Ustaw w VSCode wielkość Tabulacji na 4 spacje: "editor.tabSize": 4, "editor.insertSpaces": true

# DOBRZE
def funkcja():
    if True:
        print("Cztery spacje wcięcia")
        print("Konsekwentnie")

# ŹLE - mieszane wcięcia
def funkcja():
  if True:
      print("Chaos")

Długość linii: 

Ograniczaj linie do maksymalnie 79 znaków (lub 72 w przypadku komentarzy i dokumentacji).

Puste linie: 

Oddzielaj klasy i funkcje najwyższego poziomu dwiema pustymi liniami. Wewnątrz klas metody oddzielaj jedną pustą linią.

# DOBRZE
# Dwie puste linie między funkcjami na najwyższym poziomie
def pierwsza_funkcja():
    return "Pierwsza"


def druga_funkcja():
    return "Druga"


# Dwie puste linie między klasami
class MojaKlasa:
    # Jedna pusta linia między metodami
    def metoda1(self):
        pass
    
    def metoda2(self):
        pass


# Jedna pusta linia dla oddzielenia logicznych sekcji
def przetwarzaj_dane(dane):
    # Walidacja
    if not dane:
        return None
    
    # Przetwarzanie
    wynik = []
    for element in dane:
        wynik.append(element * 2)
    
    # Zwracanie
    return wynik

4. Importy

Importy na początku pliku, każdy w osobnej linii, pogrupowane według kategorii.

# DOBRZE - kolejność i grupowanie
# 1. Biblioteka standardowa Pythona
import os
import sys
from datetime import datetime

# 2. Biblioteki third-party (pip)
import numpy as np
import pandas as pd
from flask import Flask, render_template

# 3. Własne moduły
from my_module import my_function
from my_package.utils import helper


# ŹLE - wszystko pomieszane
from flask import Flask
import os
from my_module import my_function
import numpy as np


# DOBRZE - każdy import osobno
import os
import sys
import json

# ŹLE - wiele importów w jednej linii
import os, sys, json

# DOBRZE - z tego samego modułu można
from datetime import datetime, timedelta, date

# DOBRZE - jeśli importów jest dużo, dziel na linie
from datetime import (
    datetime,
    timedelta,
    date,
    time,
    timezone
)

# ŹLE - NIGDY nie rób wildcard imports
from module import *

5. Spacje wokół operatorów

Używaj spacji dla czytelności, ale konsekwentnie.

# DOBRZE - operatory arytmetyczne
x = 5 + 10
y = x * 2
z = (x + y) / 2

# ŹLE - brak spacji
x=5+10
y=x*2

# DOBRZE - operatory porównania
if x == 5:
    print("x wynosi 5")

if y >= 10 and z < 20:
    print("Warunek spełniony")

# DOBRZE - przecinki (spacja po, nie przed)
lista = [1, 2, 3, 4, 5]
funkcja(a, b, c)
slownik = {'klucz': 'wartość', 'klucz2': 'wartość2'}

# ŹLE
lista = [1,2,3,4,5]
lista = [1 , 2 , 3]  # Spacja przed przecinkiem

Argumenty domyślne – specjalny przypadek:

# DOBRZE - brak spacji w definicji funkcji
def funkcja(arg1, arg2=10, arg3="default"):
    pass

# ŹLE - spacje w definicji
def funkcja(arg1, arg2 = 10, arg3 = "default"):
    pass

# ALE w wywołaniu funkcji - spacje są!
funkcja(arg1=5, arg2=20, arg3="custom")

Slicing – brak spacji:

# DOBRZE
lista[1:5]
lista[::2]
lista[1:5:2]

# ŹLE
lista[1 : 5]
lista[: : 2]

6. Konwencje nazewnictwa

Różne elementy mają różne style nazewnictwa.

snake_case – małe litery z podkreśleniami

# DOBRZE - zmienne, funkcje, metody
user_name = "Jan"
total_count = 100

def calculate_sum(a, b):
    return a + b

def get_user_data():
    pass

PascalCase – każde słowo z wielkiej

# DOBRZE - klasy i wyjątki
class UserAccount:
    pass

class DatabaseConnection:
    pass

class InvalidEmailError(Exception):
    pass

UPPER_CASE – wielkie litery z podkreśleniami

# DOBRZE - stałe
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30
PI = 3.14159
API_KEY = "secret-key-123"

Specjalne konwencje:

# Jeden podkreślnik - "chroniony" atrybut
class MyClass:
    def __init__(self):
        self._internal_variable = 10  # Nie używaj z zewnątrz

# Dwa podkreślniki - "prywatny" (name mangling)
class MyClass:
    def __init__(self):
        self.__private_variable = 20

# Dwa podkreślniki z obu stron - metody magiczne (dunder)
class MyClass:
    def __init__(self):  # Konstruktor
        pass
    
    def __str__(self):  # Reprezentacja string
        return "MyClass instance"

7. Komentarze

Komentarze powinny być kompletnymi zdaniami, aktualne i wyjaśniać „dlaczego”, nie „co”.

# DOBRZE - wyjaśnienie złożonej logiki
# Sprawdzamy czy rok jest przestępny zgodnie z regułą:
# Rok podzielny przez 4 jest przestępny,
# CHYBA ŻE jest podzielny przez 100,
# ALE JEŚLI jest podzielny przez 400, to jednak jest przestępny
if (year % 4 == 0 and year % 100 != 0) or (year % 400 == 0):
    return True

# ŹLE - komentarz powtarza kod
# Zwiększ x o 1
x = x + 1

# DOBRZE - komentarz inline z dwoma spacjami
result = calculate(x, y)  # Kompensata za border

# ŹLE - brak spacji
result = calculate(x, y)# Komentarz

8. Porównania

Używaj właściwych operatorów do porównań, np. is, is not, == itp.

Interaktywna konsola Pythona (REPL)

REPL to skrót od Read-Eval-Print Loop (Czytaj-Wykonaj-Wyświetl-Powtórz). To interaktywne środowisko, w którym możesz pisać kod Pythona linia po linii i natychmiast widzieć rezultaty.

Uruchamianie REPL

Otwórz terminal i wpisz:

python

Zobaczysz coś podobnego:

Python 3.12.0 (main, Oct  2 2023, 14:30:00)
Type "help", "copyright", "credits" or "license" for more information.
>>>

Znak >>> to prompt – oznacza, że Python czeka na Twoje polecenie.

Podstawowe użycie REPL

>>> 2 + 2
4
>>> 10 * 5
50
>>> 100 / 3
33.333333333333336
>>> 2 ** 10
1024
>>> print("Hello, World!")
Hello, World!
>>> "Python"
'Python'

Wyjście z REPL

Są trzy sposoby:

>>> exit()
lub
>>> quit()

lub skrót klawiszowy: Ctrl + Z, potem Enter

IDLE – wbudowane IDE Pythona

IDLE (Integrated Development and Learning Environment) to prosty edytor kodu i środowisko programistyczne instalowane automatycznie razem z Pythonem. Jest to oficjalne, darmowe narzędzie stworzone specjalnie dla osób rozpoczynających naukę programowania.

Nazwa IDLE to także gra słów – jest to hołd dla Erica Idle’a, jednego z członków grupy Monty Python (od której Python wziął swoją nazwę).

IDLE znajdziesz w menu Start Windowsa po instalacji Pythona

Po uruchomieniu IDLE zobaczysz Python Shell – interaktywną konsolę Pythona. Działasz w niej jak w REPL

Artykuł 2. Python – pierwszy program, wyświetlanie danych, komentarze pochodzi z serwisu Kama Kaczmarek.