Kommentera aldrig kod

Nu när man precis slutat skolan och ska ge sig ut i arbetslivet känns det relevant att reflektera lite över vad man lärt sig. Framförallt måste jag titta på vart gränsen mellan nitisk lärare och god praxis går. När jag studerat har jag många gånger fått höra hur viktigt det är att kommentera min kod. Och att det är bättre att kommentera rikligt än att inte kommentera alls. Detta leder ofta till att man har kommentarer som egentligen säger exakt samma saker som koden redan gör.

Att sitta och kommentera kod man redan skrivigt är ofta ganska onödigt, och om man måste ha kommentarer för att man gjort så komplex kod är det något som är seriöst fel. Programmering ska inte vara komplicerat. Det ska bestå av många små enkla lösningar som tillsammans arbetar för att lösa ett större och mera komplext problem. Det är i alla fall enligt mig en av grundpelarna inom de flesta typer av programmering.

 
for i in p_range:
   if checkP(h, i):
       save.append(i)

De tre rader kod ovan säger inte så mycket egentligen. Varken vad de försöker göra eller varför de gör så. Det enda vi kan se är hur koden försöker lösa problemet. När jag dokumenterar min kod arbetar jag ofta med tre frågor. Var, varför och hur. Detta sett att angripa problemet hjälper ofta när man försöker se vad och vilka kommentarer som kan vara relevanta.

 
# Check if a port is open, then save it in a list.
for i in p_range:
   if checkP(h, i):
       save.append(i)

Samma tre rader kod som innan, denna gång med en kommentar som svarar på frågan om vad koden försöker göra. Somliga hävdar nog att detta är tillräkligt och att vi nu har dokumenterat nog. Jag hävdar att det är bättre att göra på följande sätt.

 
for port in portRange:
    if isOpen(hostname, port):
        open_ports.append(port)

Fortfarande samma tre rader kod. Men denna gång har jag valt att byta namn på variablerna istället. Och nu kändes den kommentaren jag hade tidigare överflödig, så jag har valt att plocka bort den. Som utvecklare tycker jag det står ganska klart vad dessa tre rader kod försöker göra och även hur de löser problemet.

Den tredje frågan om varför problemet löses på detta sätt är alltid den svåraste att förklara. I detta fall kommer dessa tre rader kod från en portscanner jag hacka ihop lite snabbt för någon vecka sen. Och om du inte förstår varför en portscanner går igenom en for-loop och sen utför funktionen isOpen på varje port har du fortfarande mycket att lära. (Och varför jag ville ha en portscanner var för att jag inte kunde installera nmap på den maskinen jag satt på, kunde inte installera något alls)

(Exemplen ovan är skriva i programmeringsspråket Python)