Python Code Conventies¶

Bij het programmeren is het belangrijk dat je broncode leesbaar en begrijpelijk is. Als we ons allemaal aan dezelfde afspraken houden, wordt het makkelijker code te schrijven en onderhouden, en ook om daarbij als team samen te werken. We maken daarom gebruik van de “Hogeschool van Amsterdam Code Conventions”,  op basis van PEP 8.

Code Conventions¶

Als je code schrijft voor projecten in de HvA-propedeuse hou je je aan de volgende afspraken:

Code commentaar¶

Commentaar voeg je toe om de werking van de code toe te lichten. Hierbij is het belangrijk om te beschrijven waarom die code is toegevoegd, niet wat de code doet. Commentaar schrijf je in het Engels.

Dus niet:

# increase the index by 1`
index += 1

Maar:

# refer to the next student in line
index += 1

Multiline docstrings¶

Bij functies staat het doel van de functie, de mee te geven argumenten én de return value beschreven in een doc string. Een doc string is een blok commentaar over meerdere regels. Doc strings worden geschreven in het Engels. Dat ziet er als volgt uit:

def summation(no1: int, no2: int) -> int:

    """
    This function adds two numbers, no1 and no2.

    Keyword arguments:
        no1: first number of the equation, any positive or negative integer
     no2: second number of the equation, any positive or negative integer

    Return values:
        added_values: total of two values, integer value
    """

    added_values: int = no1 + no2
    return added_values

Tip

Als je de multiline docstring goed schrijft zal die als function hint te zien zijn in Visual Studio Code.

Naamgeving¶

Variabelen, functies, methoden en classes hebben duidelijke namen waaruit het bedoelde gebruik duidelijk wordt. Voor de naamgeving wordt gebruik gemaakt van snake case (kleine letters, met underscores tussen woorden). Namen schrijf je in het Engels.

Dus niet:

ThisIsAVariable: int = 10
var1: str = "sth"
x: float = 8.5

Maar:

max_tries: int = 10
vowels_removed: str = "sth"
grade_received: float = 8.5

Typehinting¶

Python is een dynamically typed language. Dat houdt in dat Python het datatype van een variabele automatisch bepaalt op basis van de context waarin de variabele wordt gebruikt. Dit kan problemen opleveren bij het programmeren. Om deze problemen makkelijker op te sporen gebruik je typehinting. Bij het aanmaken van een variabele geef je direct aan welk datatype je verwacht erin op te slaan. Dit doe je door tussen de variabele-naam en de toewijzing het datatype aan te geven. Bij functies geef je aan welk datatype je verwacht voor de argumenten, én het datatype van de return-waarde. Dit werkt als volgt:

max_tries: int = 10

def summation(no1: int, no2: int) -> int:

    """
    This function adds two numbers, no1 and no2.

    Keyword arguments:

        no1: first number of the equation, any positive or negative integer
        no2: second number of the equation, any positive or negative integer

    Return values:
        added_values: total of two values, integer value
    """

    added_values: int = no1 + no2
    return added_values

Code formatteren¶

Om code te formatteren (bijvoorbeeld uitlijnen, of variabele-waarden in een string toevoegen) gebruik je f-strings.

Dus niet:

min_passengers: int = 3
max_passengers: int = 10

print("Het minimum aantal passagiers is " + min_passengers + " en het maximum aantal passagiers is " + max_passengers + ".")

Maar:

min_passengers: int = 3
max_passengers: int = 10

print(f"Het minimum aantal passagiers is {min_passengers} en het maximum aantal passagiers is {max_passengers}.")

Leesbaarheid code¶

Daarnaast zijn er een aantal regels die je moet volgen om de code leesbaar en duidelijk te houden:

De maximale regellengte is 120 karakters, bij voorkeur 100.
Indents bestaan uit 4 spaties.
Modules importeer je bovenaan het programma.
Verwijder statements die weg kunnen en maak je programma “schoon”.
Verwijder code die “commented out” is, dus in commentaar staat en niet wordt gebruikt.
Vermijdt magic numbers: getallen die ineens in de code voorkomen en waarvan het gebruik niet duidelijk is.
Organiseer je programma in blokken code die bij elkaar horen. Zet witregels tussen losse blokken code.

Oefening

Gebruik bovenstaande checklist om je code te controleren en te verbeteren. Laat zien welke verbeteringen je hebt doorgevoerd en documenteer dit in een markdown document dat je upload naar je repository.