==== Coding style ====

Tato stránka obsahuje souhrn informací a doporučení, jak psát krásné, čitelné a konzistentní programy v jazyce Python.  
Cílem je, aby byl kód přehledný nejen pro autora, ale i pro ostatní, kteří s ním mohou později pracovat.  
Vycházíme z obecných zásad a doporučení známých jako [[https://peps.python.org/pep-0008/ | PEP 8]], což je oficiální průvodce stylem pro Python. Níže jsou shrnuty nejdůležitější body.

=== Názvy proměnných, funkcí a tříd ===
Dobré pojmenování je základem čitelného kódu. **Název by měl jednoznačně vystihovat, co daná proměnná nebo funkce dělá.** Vyhýbejte se obecným názvům jako ''a'', ''b'' nebo ''pole'', pokud nemají jasný význam v daném kontextu. 

Python rozlišuje mezi různými konvencemi pojmenování. Naše doporučení:

  * proměnné a funkce: používají se malá písmena a podtržítka
<code python>
student_name = "Jana"

def calculate_average(scores):
    return sum(scores) / len(scores)
</code> 
  * třídy: začíná velkým písmenem
<code python>
class ExcellentStudent:
    pass
    
class Excellent_student:
    pass
    
class Excellent_Student:
    pass
</code>
  * konstanty: píšeme velkými písmeny
<code python>
MAX_SCORE = 100
</code>

V rámci ALPu vás nebudeme nutit používat přesně tuto konvenci. Důležitější než konkrétní styl je **konzistence** — to znamená, že v celém programu používáte stejný způsob pojmenování pro stejny typ proměnné. **Vyberte si styl a držte se ho!**

<code python>
# Špatně - nekonzistentní styl:
def add_numbers(summand1, summand_2):
    return summand1 + summand_2
    
def multiplyNumbers(factor_one, factortwo):
    return factor_one * factortwo
    
# Spravně - konzistentní styl:
def add_numbers(summand1, summand2):
    return summand1 + summand2
    
def multiply_numbers(factor1, factor2):
    return factor1 * factor2
</code>

Důležitá je také konzistence v rámci jazyka. Ideální je pojmenovávat proměnné a funkce v angličtině, je však přijatelné používat i češtinu. **V rámci jednoho programu ale používejte jen jeden jazyk.**

=== Odsazení a mezery ===

V Pythonu odsazení nahrazuje složené závorky a je zásadní pro správnou funkčnost kódu. Správné odsazení výrazně zlepšuje čitelnost, použivejte **minimálně 2 mezery** pro každou úroveň odsazení, **maximálně 4**. Opět, nejdůležitější je konzistence.

V ramci aritmetiky je někdy vhodne vložit mezery pro lepší čitelnost. V tomto případě dbejte na zdůraznení priority operací, ale dbejte na konzistenci. Pokud dávate mezeru před operátor, měla by být i po něm.

<code python>
# Správně
a=2*b-c
a = 2*b - c
a = 2 * (b-c)
a = 2*(b-c)

# Špatně
a = 2 * b-c # násobení ma vyšší prioritu než sčítání
a=2*( b- c)
a= 2* b -c
a = b*c + d * e # nekonzistentní
</code>

Pro lepší přehlednost doporučujeme oddělovat **logicky související části kódu** prázdnými řádky.  
Pomáhá to čtenáři pochopit strukturu programu a zjednodušuje orientaci.

<code python>
def calculate_area(radius):
    return 3.14 * radius * radius


def print_area(radius):
    area = calculate_area(radius)
    print(f"Area is {area}")


r = 5
print_area(r)
</code>

=== Používejte funkce ===

Funkce jsou základní stavební kameny čitelného a modulárního kódu.  
Díky funkcím:

  * se kód stává přehlednějším – jednotlivé bloky mají jasný účel,  
  * je snadnější jej testovat a ladit,  
  * lze jej znovu použít na více místech programu.

Příklad správného použití funkcí:

<code python>
def greet(name):
    print(f"Hello, {name}!")

def calculate_average(scores):
    return sum(scores) / len(scores)

# Použití funkcí
student_scores = [80, 90, 70]
avg = calculate_average(student_scores)
greet("Jana")
</code>

Špatný přístup – opakování kódu místo funkcí:

<code python>
student_scores = [80, 90, 70]
avg = sum(student_scores) / len(student_scores)
print(f"Hello, Jana!")

student_scores2 = [60, 75, 85]
avg2 = sum(student_scores2) / len(student_scores2)
print(f"Hello, Petr!")
</code>

== Konzistentní návratové hodnoty ==

Funkce by měly vracet **stejny počet hodnot** a nejlépe stejného typu.  
Pokud funkce někdy vrací jednu hodnotu a jindy více, může to vést k chybám a ztěžuje čtení kódu.

<code python>
# Správně – vždy vrací hodnotu a index jako tuple
def find_value_index(lst, target):
    for idx, value in enumerate(lst):
        if value == target:
            return value, idx
    return None, -1

# Použití
numbers = [10, 20, 30, 40]
val, idx = find_value_index(numbers, 30)  # vrátí (30, 2)
val2, idx2 = find_value_index(numbers, 50)  # vrátí (None, -1)
</code>

=== Globální proměnné ===

Globální proměnné ztěžují čitelnost a údržbu kódu, protože jakákoliv část programu je může měnit.  
Doporučujeme je používat co nejméně, a na místo toho předávat hodnoty do funkcí jako parametry a vracet výsledky.

<code python>
# Špatně – globální proměnné
total_score = 0

def print_total():
    print(f"Total score is: {total_score}")

def add_score(score):
    global total_score
    total_score += score

add_score(10)
add_score(20)
print_total()
</code>

<code python>
# Správně – parametry a návratové hodnoty

def print_total(total_score):
    print(f"Total score is: {total_score}")

def add_score(current_total, score):
    return current_total + score

total_score = 0
total_score = add_score(total_score, 10)
total_score = add_score(total_score, 20)
print_total(total_score)
</code>

Dobrou praxí je umístit **hlavní blok programu do funkce ''main()''**, čímž se omezuje používání globálních proměnných a kód je přehlednější.

<code python>
def print_total(total_score):
    print(f"Total score is: {total_score}")

def add_score(current_total, score):
    return current_total + score

def main():
    total_score = 0  # lokální proměnná v main
    total_score = add_score(total_score, 10)
    total_score = add_score(total_score, 20)
    print_total(total_score)

# Spuštění hlavní funkce
if __name__ == "__main__":
    main()
</code>

**Tip:**  
Použití ''main()'' zajišťuje, že všechny proměnné jsou lokální pro hlavní blok, a snižuje šanci, že někdo omylem použije globální proměnnou. Tato struktura je standardní u většiny Python projektů.


=== Komentáře ===

Komentáře nejsou povinné, ale velmi pomáhají čitelnosti kódu.  
Pokud považujete za užitečné vysvětlit, **co funkce dělá** nebo **jak kód funguje**, doporučujeme je zahrnout.


== 1. Komentáře uvnitř funkcí (docstring) ==

Každá funkce může mít krátký popis pomocí **docstringu**, který vysvětluje její účel a případně parametry či návratovou hodnotu:

<code python>
def calculate_average(scores):
    """
    Returns the average of a list of scores.

    Parameters:
    scores (list): list of numerical values

    Returns:
    float: average value
    """
    return sum(scores) / len(scores)
</code>

== 2. Komentáře v hlavním bloku kódu ==

Komentáře v hlavním bloku kódu mohou obsahovat stručný popis pro přehled. Avšak v příkladech níže nejsou zcela nutné díky vhodnému pojmenování proměnných.

<code python>
# list of student scores
student_scores = [80, 90, 70]

# calculate average using the function
average = calculate_average(student_scores)

# greet the student with their average score
print(f"Hello, the average score is {average}")
</code>