Níže uvedený text pochází z prvního vydání. Nad tímto textem se nachází aktuální stav po revizi směřující k druhému vydání.

Styl zápisu kódu

Komentáře

V kapitole Další posloupnosti jsme se již o komentářích bavili. Nicméně, s komentáři lze dělat i další věci a o některých z nich se zde zmíním:

Informace o historii verzí

Bývá dobrým zvykem vytvořit na začátku každého souboru hlavičku. Měly by v ní být uvedeny takové detaily, jako je datum vytvoření, jméno autora, datum, verze a obecný popis, týkající se obsahu^[1]. Často se uvádí seznam záznamů o změnách. Takový blok textu se uvádí formou komentáře:

#############################
# Modul: Spam.py
# Autor: A.J.Gauld
# Datum: 1999/09/03
# Verze: Draft 0.4
#
# Popis: Tento modul vytvoří objekt Spam, který můžeme kombinovat
# s kterýmkoliv jiným typem objektu Jidlo, abychom vytvořili zajímavé
# pokrmy.
#
###############################
# Log:
# 1999/09/01 AJG - Vytvoření souboru.
# 1999/09/02 AJG - Opravena chyba v cenové strategii.
# 1999/09/02 AJG - Tentokrát už jsem to udělal správně!
# 1999/09/03 AJG - Přidána grilovací metoda (viz požadavek #1234)
################################
import sys, string, food
...

Zakomentování nadbytečného kódu

Tato technika se často používá k izolaci chybného úseku kódu. Předpokládejme například, že program čte nějaká data, zpracovává je, tiskne výstup a potom ukládá výsledek zpět do datového souboru. Pokud výsledky neodpovídají našemu očekávání, pak bychom rádi zabránili zpětnému ukládání (chybných) dat, abychom tento soubor neporušili. Odpovídající kód bychom mohli jednoduše odstranit. Méně radikální přístup spočívá v tom, že dané řádky jednoduše změníme na komentář, například takto:

data = ctiData(soubor)
for polozka in data:
    vysledky.pridej(vypoctiVysledek(polozka))
tiskniVysledky(vysledky)
######################
# Následující kód zakomentujeme až do doby,
# kdy bude opravena chyba ve funkci vypoctiVysledek,
# která vyhodnocuje výslednou položku.
#
# for polozka in vysledky:
#     soubor.ulozit(polozka)
######################
print 'Konec programu'

Jakmile je chyba odstraněna, můžeme jednoduše smazat komentářové značky a kód se tím stane znovu aktivním.

Dokumentační řetězce

Komentáře, které dokumentují, co daná funkce nebo modul dělají, můžeme použít ve všech jazycích. Ale jen pár jazyků — jako je Python a Smalltalk — jdou o krok dále a umožňují nám dokumentovat funkci takovým způsobem, že mohou být použity v integrovaném prostředí pro realizaci interaktivní nápovědy během programování. V jazyce Python toho dosáhneme použitím """dokumentačních řetězců""":

class Spam:
    """Maso určené ke kombinování s ostatními potravinami.
 
    Ve spojení s jinými potravinami se dají vytvořit zajímavá jídla.
    Obsahuje mnoho živin a může být připraveno mnoha různými způsoby."""
    
    def __init__(self):
        ...

print Spam.__doc__

Poznámka překladatele k českým znakům v ukázce: Pokud si bude Python stěžovat, že používáte nepovolené znaky, zkuste je nahradit česká písmenka ceskymi (bez diakritiky). K tomuto problému se ještě vrátíme na jiných místech.

Poznámka: Dokumentační řetězec můžeme vytisknout jako obsah speciální proměnné __doc__. Dokumentační řetězce mohou být definovány pro moduly, funkce, třídy a metody tříd. Vyzkoušejte například:

import sys
print sys.__doc__

Odsazování

Jde o jedno z nejžhavějších témat, o kterém se mezi programátory debatuje. Skoro se zdá, že každý programátor má svou vlastní představu o nejlepším způsobu odsazování kódu. Byly vypracovány některé studie, které ukazují, že přinejmenším některé z faktorů mají význam větší, než kosmetický — usnadňují nám pochopení kódu.

Důvody pro debatu jsou jednoduché. Ve většině programovacích jazyků má odsazování čistě kosmetický význam; jde o pomůcku pro čtenáře. (Pokud se týká jazyka Python, zde je odsazování nutné a má zásadní vliv na správnou funkčnost programu!) Takže například:

FOR I = 1 TO 10
    PRINT I
NEXT I

Tento zápis je interpretem jazyka BASIC chápán jako naprosto shodný se zápisem:

FOR I = 1 TO 10
PRINT I
NEXT I

Zápis s odsazením se nám prostě lépe čte.

Podstatné je, že odsazování by mělo odrážet logickou strukturu kódu. Mělo by vizuálně odrážet tok řízení v programu. Tady nám pomáhá, když bloky kódu vypadají jako bloky (v geometrickém smyslu)…

XXXXXXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXX

… což se čte lépe než následující zápis…

XXXXXXXXXXXXXXXXXXXXX
  XXXXX
    XXXXXXXXXXXX
    XXXXXXXXXXXX
    XXXXXXXXXXXX
  XXXXX

protože je lépe vidět, co k bloku patří. Studie prokázaly výrazné zlepšení srozumitelnosti v případech, kdy odsazování odráží strukturu logických bloků. V malých příkladech, se kterými jsme se dosud setkali, se to nemusí zdát důležité. Ale jakmile začnete psát programy se stovkami a tisíci řádků, důležitost vhodného odsazování výrazně vzroste.

Jména proměných

Jména proměných, která jsme dosud používali, nevyjadřovala žádný význam. Důvodem bylo především to, že jsme je použili jen pro ilustraci použitých technik. Obecně je ale mnohem lepší, kdy jména vašich proměnných vyjadřují to, co jimi chcete reprezentovat. Například v naší ukázce programu pro generování tabulek násobků jsme použili proměnnou nasobitel, která určovala, která z tabulek se tiskne. Je to určitě smysluplnější, než kdybychom použili jenom n — fungovalo by to stejně a ušetřili bychom si psaní.

Jde o kompromis mezi srozumitelností a úsilím. Obecně se dá říct, že nejlepší je volit krátká, ale výstižná jména. Příliš dlouhá jména by nás mátla a opakované zápisy jejich správné podoby by byly obtížné. Místo proměnné nasobitel jsme mohli použít například proměnnou tabulka_kterou_tiskneme, ale takové jméno je mnohem delší a přitom není o nic jasnější.

Modulární programování

Později si toto téma vysvětlíme podrobněji. Teď bych chtěl vysvětlit jen hlavní myšlenku a — což je důležité — jak můžeme moduly využít k ušetření práce. Až dosud se všechny programy ztrácely v okamžiku, kdy jsme ukončili Python.

Použití příkazového řádku interpretu jazyka Python v interaktivním režimu (>>>)je velmi vhodné pro rychlé vyzkoušení nápadů. Ale jakmile činnost interpretu ukončíme, vše je ztraceno. Z dlouhodobého hlediska chceme umět napsat programy, které budeme opakovaně spouštět. Dosáhneme toho vytvořením textového souboru s připonou .py. (Jde pouze o konvenci — můžete použít jakoukoliv jinou příponu. Ale podle mého názoru je dobré takové konvence dodržovat.) Poté můžeme program spustit tím že na příkazový řádek (v dosovém okně nebo v okně unixovského shellu) napíšeme:

$ python spam.py

Poznámka pro uživatele Unixu: První řádek pythonovského skriptu by měl obsahovat posloupnost #! následovanou plným názvem (i s cestou) programu python. (Jeho umístění můžete nalézt tak, že na vyzývací řádek shellu napíšete $ which python.

V mém systému by řádek vypadal takto:

#! /usr/local/bin/python

To vám umožní skript spouštět, aniž byste museli explicitně psát python. (Pozor! Skriptu musíte navíc nastavit příznak spustitelnosti.)

$ spam.py

V prostředí Windows/Mac je tento řádek neškodný. Takže pokud uživatelé předpokládají, že se jejich kód někdy bude pouštět také v Unixu, mohou jej do skriptu přidat.

Poznámka pro uživatele Windows: Pod Windows můžete Průzkumníkem nastavit vazbu .py souborů na interpret jazyka Python. To vám umožní spouštět pythonovské programy jednoduchým poklepáním na ikonu souboru. Tuto vazbu již pravděpodobně nastavil instalační program. Můžete si to ověřit tím, ža nalezneta nějaké .py soubory a pokusíte se je zpustit. Pokud se spustí (i když se může objevit chybové hlášení iterpretu jazyka Python), je vazba nastavena.

Další výhoda ukládání programů do souborů spočívá v tom, že můžete opravovat chyby, aniž byste museli znovu napsat celý fragment nebo, to se týká IDLE, aniž byste museli kurzor přesunovat nahoru, nad chybová hlášení za účelem opakovaného výběru kódu. IDLE umožňuje otevření soubou pro editaci a jeho současné spuštění prostřednictvím menu Edit|Run module.

Od této chvíle v příkladech obvykle nebudu ukazovat vyzývací posloupnost >>>. Budu předpokládat, že program zapisujete do souboru a soubor spouštíte buď z IDLE nebo z příkazového řádku shellu nebo DOSového okna, což je můj oblíbený způsob.