Hur man skriver kommentarer i Python för ren och läsbar kod

Betydelsen av Kommentarer för Tydlig Pythonkod

Att skriva välformulerade kommentarer i Python gör koden mer tillgänglig och begriplig för andra programmerare och testare.

Tydlig kod med konsekvent struktur, beskrivande variabelnamn och korrekt indragning är som en välskriven bok – lätt att förstå och underhålla.

I dagens läge är det sällsynt att en enskild person skriver all kod för en hel applikation eller mjukvara. Oftast arbetar ett team eller en grupp tillsammans mot ett gemensamt mål. I dessa situationer är ren och lättläst kod avgörande för effektivt samarbete.

Programmerare och testare strävar ständigt efter att leverera buggfri mjukvara. Ren och lättförståelig kod underlättar den här processen genom att göra felsökningen enklare och mer precis. Även om fel skulle uppstå i produktionsmiljön, är det lättare att rätta till fel i tydlig kod.

Viktigast av allt, ren och välskriven kod lever längre, eftersom den behåller sin klarhet över tid.

Kort sagt, ren och lättläst kod är avgörande för att skapa långlivad programvara. Men hur uppnår man detta? Ett effektivt sätt är att använda kommentarer.

Har du inte upplevt frustrationen när du återvänder till komplex kod du själv skrivit och inte förstår hur den fungerar? Detta kan undvikas genom att skriva kommentarer.

Kommentarer är beskrivande text som förklarar vad koden gör. De kan skrivas på vilket språk som helst, men engelska är att föredra eftersom det är ett universellt språk.

När du återvänder till din kod efter dagar eller år kommer kommentarerna att påminna dig om vad du skrev och varför.

Dessutom underlättar de för andra utvecklare att förstå koden. Därför kan kod som dokumenterats med kommentarer leva vidare även i frånvaro av den ursprungliga programmeraren.

Konflikter kan också uppstå när man hanterar olika programmeringsspråk, speciellt i team. Även här kommer kommentarerna till nytta. Om du inte är bekant med programmeringsspråket som en kollega använt, kan kommentarerna hjälpa dig att förstå logiken bakom koden.

Koddokumentation är ett mer omfattande sätt att underhålla källkoden och underlätta samarbetet i teamet. Den innehåller detaljerad information om koden, inklusive design, funktionalitet, arkitektur och komponenter.

Kommentarer bidrar till denna koddokumentation. Välskrivna kommentarer kan direkt överföras till dokumentationen och ger utvecklare information om både vad, varför och hur koden fungerar.

  • Kommentarer förklarar inte bara vad koden gör utan också programmerarens avsikter bakom varje rad. Det underlättar felsökning och gör det tydligt var koduppdateringar bör göras.
  • Kommentarer kan antingen beskriva hela kodblock eller enskilda rader. Detta ökar läsbarheten och förståelsen för både dig och andra utvecklare.
  • Kommentarer kan dela upp koden i logiska sektioner, vilket underlättar navigeringen.
  • Kommentarer bör beskriva förväntade indata, utdata och användningsfall, vilket hjälper testare att förstå koden.
  • Korrekt dokumenterade kommentarer ökar den totala läsbarheten av koddokumentationen.

I Python börjar kommentarer med symbolen #. All text på en rad som börjar med # ignoreras av kompilatorn och behandlas som en kommentar.

Kompilatorn ignorerar kommentarerna när koden körs, men de är synliga i källkoden för att tjäna sitt syfte.

Det finns huvudsakligen tre typer av kommentarer.

Den vanligaste typen är enradskommentarer som börjar med #. En hel rad som börjar med # används för kommentaren.

Så här skriver du en enradskommentar:

# Det här är en enradskommentar.

Python stöder inte flerradskommentarer direkt, men det finns sätt att åstadkomma detta.

Du kan använda # för varje rad i en flerradskommentar.

# Det här är den första kommentaren.
# Det här är den andra kommentaren.
# Det här är den sista kommentaren.

#3. Python Docstrings

Ett populärt sätt att skriva flerradskommentarer är att använda stränglitteraler med trippla citattecken – ”””…”””. Text som skrivs mellan tre citattecken ignoreras av Python-kompilatorn.

Dessa kommentarer kallas docstrings när de skrivs direkt efter funktioner, moduler och klasser.

Här är syntaxen:

""" Flerradskommentarer med docstrings i Python. """

Tydliga och detaljerade kommentarer ökar kodens läsbarhet och underhållsvänlighet. Här är några bästa praxis för tydliga kommentarer i Python.

Kommentarer bör inte bara beskriva vad koden gör utan också syftet och avsikten bakom varje rad.

Ta bort inaktuella kommentarer och se till att uppdatera dem när du gör ändringar i koden.

Skriv korta och koncisa kommentarer istället för långa beskrivningar.

Dåligt exempel: Funktionen tar a och b som indata, beräknar a + b och returnerar värdet.
Bra exempel: Funktionen returnerar summan av a och b.

Att använda meningsfulla och beskrivande variabel- och funktionsnamn kan minska behovet av många kommentarer.

Ska man skriva kod först eller kommentera först? Det är bäst att kommentera före kodningen. Skriv kommentarerna och sedan motsvarande kod. Då kan du först tänka igenom logiken och sedan översätta den till kod.

# Returnerar sant om cnt är mindre än 1.
return cnt < 1

Använd ett konsekvent format för kommentarer, inklusive mellanslag, indrag och typ av kommentarer. Det gör koden tydligare och lättare att läsa.

Använd docstrings för att beskriva funktioner och klasser, som i det följande exemplet:

def add_num(a,b):
    """ Denna funktion returnerar summan av a och b """
    sum = a+b
    return sum

Undvik onödiga kommentarer. Följande kod behöver t.ex. ingen kommentar för att förstås:

ans = 42

#1. Visual Studio Code Editor

Visual Studio Code Editor är en populär IDE (Integrated Development Environment) från Microsoft för utvecklingsmiljöer. Med inbyggt stöd för Node.js och JavaScript stödjer den även många andra programmeringsspråk.

Denna anpassningsbara editor har olika tillägg för olika funktioner. ”Bättre kommentarer” är ett sådant tillägg som hjälper dig att skapa mer användarvänliga kommentarer.

Du kan kategorisera dina kommentarer som varningar, frågor, höjdpunkter etc. för att göra det lättare att navigera i koden.

VS Code stöder redigering med flera markörer så att du kan kommentera eller redigera flera rader samtidigt.

Denna redigerare är tillgänglig för Mac, Windows och Linux.

#2. Sublime Text

Sublime Text är en populär textredigerare för stora projekt och tung kodning. Den är känd för sin snabbhet, anpassningsmöjligheter och kortkommandon.

Verktygets syntaxmarkering gör det enkelt att skilja mellan kod och kommentarer.

Liksom VS Code stöder Sublime Text redigering med flera markörer för att kommentera flera rader samtidigt.

Tack vare autokompletteringsfunktionen behöver du inte upprepa kodrader manuellt. Funktionen fyller i koden automatiskt utifrån mönster, vilket ökar kodhastigheten.

Dessutom låter ”Goto Anything”-funktionen dig smidigt växla mellan funktioner och filer i projektet.

#3. Notepad++

Notepad++ är en enkel textredigerare skriven i C++ som stöder många programmeringsspråk. Den har ett enkelt gränssnitt som fokuserar på att göra det den behöver.

Notepad++ erbjuder standardgenvägar för effektiv kommentering. Du kan även anpassa kortkommandot för att passa dina behov.

Dokumentkartan ger en översikt över projektstrukturen så att du kan navigera mellan filer, mappar och kod.

#4. Vim

Vim är en IDE som möjliggör snabbare utveckling och kodexekvering. Allt kan göras med kortkommandon, så det krävs en investering för att bemästra den.

Den tangentbordsorienterade redigeraren erbjuder många kommenteringsfunktioner genom kortkommandon. Den har kraftfulla funktioner för att navigera genom kommentarer.

Denna lättviktsprogramvara kan hantera stora filer och hundratals programmeringsspråk. Liksom alla redigerare på listan är Vim gratis och öppen källkod.

Vim är inbyggt i macOS och Linux och kan laddas ner för Windows.

#5. PyCharm

PyCharm är en kraftfull IDE som är speciellt utformad för Python-utveckling. Även om den stöder många andra programmeringsspråk, fungerar den bäst för Python. Den har kodkomplettering, syntaxmarkering och felsökningsfunktioner som är optimerade för Python.

PyCharm gör kommentering i Python mer effektiv. Den har navigationsfunktioner som hjälper dig att hoppa direkt till specifika kommentarer.

Du kan skapa egna kommentarsmallar och använda olika kommentarsmallar i PyCharm.

Med redigerarens refaktoreringsverktyg kan du enkelt uppdatera eller korrigera kommentarer.

Slutsats

Att följa kodstandarder är viktigt under hela utvecklingsprocessen och nödvändigt för att skriva produktionsfärdig kod. Koden bör vara läsbar för andra utvecklare och testare.

En viktig metod för att skapa läsbar kod är att skriva kommentarer. Kommentarer finns i nästan alla programmeringsspråk. Nu vet du hur man skriver Python-kommentarer, deras olika typer och bästa praxis för att skriva kommentarer.

Dessutom har vi listat några av de bästa kodredigerarna som underlättar kommentering.