Čistý kód v praxi – pojmenování, funkce a komentáře

Kód se čte mnohem častěji, než se píše. Čistý kód není o estetice, ale o tom, aby další člověk (nebo vy za půl roku) rychle pochopil, co kód dělá, a mohl ho bezpečně změnit. Tady jsou pravidla, která mají největší dopad, s příklady.

Pojmenování: nejlevnější dokumentace

Názvy popisují účel, ne typ

# Špatně
d = 30
lst = get_data()
flag = True

# Dobře
trial_days = 30
active_customers = get_active_customers()
is_email_verified = True

Konvence podle druhu

Co	Tvar	Příklad
Boolean	otázka (is_, has_, can_, should_)	has_paid, can_edit
Funkce	sloveso	send_invoice(), calculate_total()
Funkce vracející bool	otázka	is_overdue(invoice)
Kolekce	množné číslo	orders, user_ids
Konstanta	velká písmena	MAX_RETRIES = 3

Jednotky do názvu

timeout = 30          # sekundy? milisekundy?
timeout_seconds = 30  # jasné

Chyby se záměnou jednotek jsou skutečné a drahé. Název je nejjednodušší ochrana.

Konzistence

Pokud jednou použijete fetch_user, nepište jinde get_customer a load_client pro totéž. Jeden pojem = jedno slovo v celém projektu.

Čeština nebo angličtina?

Kód obvykle anglicky, protože jazyk, knihovny a většina vývojářů pracují v angličtině. Výjimka: doménové pojmy, které nemají přesný překlad (ico, dic, datum_splatnosti v účetním systému). Hlavně nemíchejte nahodile.

Funkce: dělají jednu věc

Funkce by měla dělat jednu věc na jedné úrovni abstrakce. Test: dokážete popsat, co dělá, jednou větou bez „a“?

# Před: validuje, počítá, ukládá a posílá e-mail
def process_order(data):
    if not data.get("email") or "@" not in data["email"]:
        raise ValueError("Neplatný e-mail")
    total = 0
    for item in data["items"]:
        total += item["price"] * item["qty"]
    if total > 1000:
        total *= 0.95
    order = Order.create(email=data["email"], total=total)
    smtp.send(data["email"], f"Objednávka {order.id} přijata")
    return order

# Po: hlavní funkce čte jako obsah kapitoly
def process_order(data):
    validate_order_data(data)
    total = calculate_total(data["items"])
    order = Order.create(email=data["email"], total=total)
    send_order_confirmation(order)
    return order

def calculate_total(items):
    subtotal = sum(item["price"] * item["qty"] for item in items)
    return apply_volume_discount(subtotal)

Každá menší funkce jde otestovat zvlášť a změna slevy nezasáhne do odesílání e-mailu.

Kolik řádků?

Pevné číslo neexistuje. Rozumné vodítko: pokud se funkce nevejde na obrazovku, nebo v ní jsou bloky oddělené komentáři („// výpočet“, „// uložení“), je to kandidát na rozdělení.

Málo parametrů

Více než 3–4 parametry jsou signál. Zvažte objekt nebo datovou třídu:

# Před
create_user("Jana", "[email protected]", True, False, "cs", None)

# Po
@dataclass
class NewUser:
    name: str
    email: str
    newsletter: bool = False
    is_admin: bool = False
    language: str = "cs"

create_user(NewUser(name="Jana", email="[email protected]", newsletter=True))

Boolean parametr (True, False) je obzvlášť nečitelný. V Pythonu pomohou pojmenované argumenty, případně vynucené pomocí *: def create_user(name, email, *, newsletter=False).

Early return místo vnořování

// Před: šipkový kód
function getDiscount(user) {
  if (user) {
    if (user.isActive) {
      if (user.orders > 10) {
        return 0.1;
      } else {
        return 0.05;
      }
    }
  }
  return 0;
}

// Po: ochranné podmínky
function getDiscount(user) {
  if (!user || !user.isActive) return 0;
  if (user.orders > 10) return 0.1;
  return 0.05;
}

Magická čísla a řetězce

if user.role == 3 and days > 14:   # co je 3? proč 14?

ROLE_ADMIN = 3
REFUND_PERIOD_DAYS = 14
if user.role == ROLE_ADMIN and days > REFUND_PERIOD_DAYS:

Ještě lépe výčtový typ (enum.Enum v Pythonu, enum v TypeScriptu nebo PHP 8.1+).

Komentáře: proč, ne co

# Špatně – opakuje kód
i += 1  # zvýšíme i o 1

# Dobře – vysvětluje důvod, který z kódu nevyčtete
# Banka vrací částky v haléřích, proto dělíme 100.
amount = response["amount"] / 100

# Dobře – varování
# Pozor: API vrací max. 100 záznamů, i když limit nastavíte výš.

Pokud potřebujete komentář k vysvětlení, co kód dělá, zkuste nejdřív lepší název proměnné nebo vytažení funkce. Zakomentovaný kód mažte – je v gitu.

Nechte to hlídat nástroje

Formátování a základní pravidla nepatří do code review, ale do nástrojů:

# Python
pip install ruff
ruff check . --fix
ruff format .

# JavaScript / TypeScript
npx eslint . --fix
npx prettier --write .

Spouštějte je automaticky v pre-commit hooku nebo v CI. Lidé pak v review řeší návrh a logiku, ne mezery.

Pravidlo skauta

„Zanech tábořiště čistší, než jsi ho našel.“ Při každé změně vylepšete jednu drobnost – přejmenujte nejasnou proměnnou, vytáhněte jednu funkci. Bez velkých přepisů, ale soustavně.