2.4. Leesbaarheid

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler

Sommige scripts zijn kort en overzichtelijk, maar de meeste zullen al snel groeien en complex worden, waardoor ze als mens niet meer goed te lezen/begrijpen zijn. En hoewel we code schrijven met als doel dat een computer de code uit kan voeren, is het toch belangrijk dat de code als mens ook nog een beetje te lezen is. In veel gevallen schrijf je namelijk code die later door iemand anders (of jezelf) nog aangepast moet kunnen worden.

2.4.1. Commentaar

Een manier om code beheersbaar te houden is het schrijven van ‘commentaarregels’. Dat zijn regels tekst die tussen de code staan, maar niet door Python zelf uitgevoerd worden. Je geeft aan dat een regel commentaar bevat door deze vooraf te laten gaan met een #-teken. Een kort voorbeeld van code mét en zonder commentaar staat hieronder.

from math import sqrt

a = 1
b = -3
c = -4

D = (b ** 2) - (4 * a * c)
x_1 = (-b + sqrt(D)) / (2 * a)
x_2 = (-b - sqrt(D)) / (2 * a)

print(x_1, x_2)

4.0 -1.0

from math import sqrt

# ABC formule
# Voer de waarden van a, b, c in. Dit script geeft dan de oplossingen van de
# vergelijking 0 = a x^2 + b x + c.

# Invoer parameters
a = 1
b = -3
c = -4

# Discriminant
D = (b ** 2) - (4 * a * c)

# Bepaal oplossingen
x_1 = (-b + sqrt(D)) / (2 * a)
x_2 = (-b - sqrt(D)) / (2 * a)

# Print de oplossingen
print(x_1, x_2)

4.0 -1.0

Als je een lange lap tekst wilt schrijven (zoals op de eerste regels van het voorbeeld), kun je deze tussen drie-keer-dubbele aanhalingstekens (""") zetten. Deze twee methoden leveren hetzelfde resultaat op.

# ABC formule
# Voer de waarden van a, b, c in. Dit script geeft dan de oplossingen van de
# vergelijking 0 = a x^2 + b x + c.

a = 1
print('...')

...

""" 
ABC formule
Voer de waarden van a, b, c in. Dit script geeft dan de oplossingen van de
vergelijking 0 = a x^2 + b x + c. 
"""

a = 1
print('...')

...

2.4.2. Naamgeving

We negeren hier even het gevaar dat we dingen gaan behandelen die wel erg voor zich spreken, vooral omdat we dit toch erg vaak fout zien gaan in de praktijk.

Geef je variabelen altijd een naam die hun inhoud zo goed mogelijk dekt. De meeste code die je zult schrijven zul je achteraf (na weken, maanden of misschien zelfs jaren) nog wel eens terug willen zien. Ook consistent gebruik van hoofd- en kleine letters, en lage-streepjes (_) helpt bij het leesbaar houden van je code.

from math import sqrt

dinges = 1
dat_andere = -3
DeLaatste = -4

tussenOplossing = (dat_andere ** 2) - (4 * dinges * DeLaatste)
opl_1 = (-dat_andere + sqrt(tussenOplossing)) / (2 * dinges)
opl_2 = (-dat_andere - sqrt(tussenOplossing)) / (2 * dinges)

print(opl_1, opl_2)

4.0 -1.0