New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Přidat dokumentační řetězce #28

Open
encukou opened this Issue Nov 5, 2018 · 4 comments

Comments

Projects
None yet
3 participants
@encukou
Member

encukou commented Nov 5, 2018

Čím víc lidí (nebo kousků kódu) používá nějakou funkci, tím je k ní důležitější napsat dokumentaci – popis toho, co ta funkce dělá. Člověk si může číst samotný kód, ale tam není všechno.

Dobrá jména funkcí a argumentů už jsou dokumentace sama o sobě. Třeba:

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

… je OK pro funkci, kterou používám někde níž v tom samém souboru. Když si ale jen přečtu kód, není jasné např. jestli je tuhle funkci dobré zavolat na řetězce, add("Hello, ", "world!").

def add(a, b):
    """
    Add two numbers

    `a` and `b` should be numbers (int or float).
    Returns the sum.
    """
    return a + b

Velké projekty, kde je potřeba aby se s kódem mohl každý co nejrychleji seznámit a korektně ho měnit, to berou fakt vážně, a dokumentace je často delší než samotný kód – viz třeba tenhle kód z Javy.
Používají se i nástroje, které ověří že každá funkce a každý argument jsou zdokumentované. To už je docela extrém (u mladšího projektu se pak může stát, že se změní kód ale neaktualizuje dokumentace, a dokumentace co neodpovídá kódu je horší než žádná dokumentace). Ale je dobré se u každého argumentu aspoň zamyslet, jestli o něm jméno říká všechno co je potřeba.

Do dokumentačních řetězců (viz materiály, nebo do vyhledávače dej docstring) je dobré psát co funkce dělá, jaké bere argumenty, co vrací. U složitějších struktur (seznam dvojic slovníků souřadnic) je dobré uvést příklad, aby si to člověk líp uvědomil
Do normálních komentářů je dobré psát jak se to dělá, jak funkce postupuje – věci, které nezajímají toho, kdo pak bude funkci volat.
Například:

def get_coordinates(data):
    """
    Get a list of tile coordinates for a map

    `data` is a dict loaded from a Tiled 1.2 JSON file.
    Returns a list of all tile coordinates, for example:
       [(0, 11), (0, 10), (0, 9), ..., (0, 0), (1, 11), (1, 10), ..., (11, 1), (11, 0)]
    """

    # Get the size of the game board from JSON
    map_field_height = data['layers'][0]['height']
    map_field_width = data['layers'][0]['width']

    # Create map - list of x, y tuples 
    # Transformation with reversed is required as the JSON tiles
    # are in the opposite y direction
    coordinates = []
    for y in reversed(range(map_field_height)):
        for x in range(map_field_width):       
            coordinates.append((x, y))

    return coordinates

Co se „štábní kultury“ týče, je dobré mít jeden řádek s krátkým (jednořádkovým!) popisem, pak řádek vynechat, a pak rozepsat detaily. Všechno v „trojitých dvojitých“ uvozovkách, """.

@anezkamll

This comment has been minimized.

Contributor

anezkamll commented Nov 5, 2018

@encukou Díky moc, upravím! 👍

@amazonkaarya

This comment has been minimized.

Contributor

amazonkaarya commented Nov 5, 2018

mám ty komentáře rozdělané pro celý Karolinin kód, pokusím se co nejdřív to znovu předělat podle tohoto

@encukou

This comment has been minimized.

Member

encukou commented Nov 6, 2018

Doporučuju je přidávat postupně, radši než všechny najednou. Ostatní pak vidí že se něco děje, je míň práce to aktualizovat když se kód změní, a dřív se přijde na případnou systematickou chybu.

@amazonkaarya amazonkaarya self-assigned this Nov 7, 2018

@encukou

This comment has been minimized.

Member

encukou commented Nov 7, 2018

Když se tak koukám do kódu, poznamenám:
Dokumentační řetězec musí být řetězec (tedy v uvozovkách; ne komentář s #) a musí být vevnitř ve funkci (hned na začátku).
Dokumentační řetězce sluší všem funkcím, i těm testovacím.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment