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

Att skriva bra kommentarer i Python kommer att tillåta andra utvecklare och testare att enkelt läsa och förstå din kod.

Ren kod med konsekvent syntax, beskrivande variabelnamn och indrag är som den första boken, lättare att förstå och underhålla.

Dessutom är det nuförtiden mindre vanligt att en individ skriver hela koden för hela applikationen eller programvaran; snarare kommer ett team eller en grupp människor att arbeta mot samma mål. I det här fallet gör ren och läsbar kod samarbetet enklare och mer effektivt.

Utvecklare och testare strävar alltid efter att distribuera buggfri programvara till produktion. Att skriva ren och läsbar kod påskyndar denna process genom att göra felsökningen enklare och mer exakt. Även om du hittar några fel i produktionen är renare kod lättare att uppdatera.

Ännu viktigare, ren och läsbar kod lever längre eftersom koden förblir fräsch med tiden.

Slutligen är det avgörande att ha ren och läsbar kod för att skapa långvarig programvara. Men frågan är, hur gör vi exakt det? Nåväl, en metod är att använda kommentarer.

Är det inte frustrerande när du har skrivit hela koden för en komplex logik, men nästa dag, när du inte kan fortsätta där du slutade? Detta händer inte när du skriver kommentarer.

Kommentarer är ett mänskligt språk som förklarar vad källkoden gör. Du kan skriva dem på vilket språk som helst, helst engelska, eftersom det är ett globalt språk.

Så när du kommer tillbaka till din källkod efter dagar eller till och med år, kommer kommentarerna att förklara för dig vad du en gång skrev.

Dessutom hjälper de andra utvecklare att enkelt förstå din kod. Det är därför koden skriven med kommentarer förblir för alltid, även i frånvaro av dess författare.

Dessutom är det ganska vanligt att ha konflikter när man hanterar olika programmeringsspråk, speciellt när man arbetar i ett team. Det är där kommentarer kommer till undsättning. Även om du inte kan programmeringsspråket för källkoden skriven av din lagkamrat, hjälper kommentarer dig att förstå logiken bakom det.

Koddokumentation är ett mer omfattande sätt att underhålla din källkod och låter ditt team samarbeta sömlöst. Den innehåller allt om koden, som design, funktionalitet, arkitektur, komponenter, etc.,

Kommentarer bidrar till och med till denna koddokumentation. Välskrivna kommentarer kan tas direkt in i koddokumentationen så att utvecklare inte bara får vad och varför utan också hur din kod.

  • Kommentarer läser inte bara upp koden utan hjälper dig också att förstå utvecklarens avsikt bakom varje rad. Så om du hittar någon bugg i framtiden vet du exakt var du ska göra koduppdateringarna.
  • Du kan skriva kommentarer som ett stycke för hela koden eller enskilda rader som förklarar vad varje kodblock gör. På så sätt låter de dig och andra utvecklare förstå koden väl, vilket förbättrar läsbarheten.
  • Kommentarer kan dela upp koden i logiska avsnitt, vilket gör kodnavigering enklare.
  • Du bör inkludera kommentarer som beskriver förväntade ingångar, utgångar och användningsfall så att en testare kan läsa din kod.
  • Slutligen, genom att lägga in välskrivna kommentarer i din dokumentation förbättras den övergripande läsbarheten av koddokumentationen.

Kommentarer i Python börjar med en hash-symbol (#). Så när du startar en rad med hash (#), så behandlas allt som skrivs på den raden som en kommentar.

När du kör koden ignorerar kompilatorn raden som börjar med hash (#) som om den inte ens existerar. Kommentarerna förblir dock synliga i källkoden för att tjäna sitt syfte.

Det finns tre huvudtyper.

Det här är de som du har sett ovan. De börjar med hash-symbolen (#). I grund och botten är raden som börjar med hash-symbolen (#) tillägnad kommentaren. Så detta kallas en enradskommentar, där du bara kan skriva en kommentar på en rad som börjar med hash (#).

Så här kan du skriva enradiga kommentarer

# This is single line comment.

Tekniskt sett stöder Python inte flerradskommentarer, men det finns sätt att uppnå detta i Python.

Du kan också använda hash (#) för att skriva kommentarer med flera rader. Varje rad du skriver ska börja med en hash-symbol (#) här.

# This is the first comment.
# This is second comment.
# This is the last comment.

#3. Python Docstrings

Ett populärt sätt att skriva flerradskommentarer är att använda bokstavliga strängar – ”””….”””. När du skriver något mellan tre citattecken ignorerar Python-kompilatorn dessa rader och kör den återstående delen i filen.

Dessa kommentarer kallas docstrings när de skrivs direkt efter funktionerna, modulerna och klasserna.

Här är syntaxen för att göra detta

""" Multi-line comments using docstrings 
in Python. """

Att skriva tydliga och detaljerade kommentarer förbättrar din kodläsbarhet och underhåll. Så här är de bästa metoderna för tydliga kommentarer i Python.

Kommentarer ska inte bara berätta vad koden gör, i stället bör de återspegla syftet och avsikten bakom varje rad.

Ta bort inaktuella kommentarer och se till att uppdatera kommentarer när du ändrar koden.

Istället för långa berättelser, skriv korta och konkreta kommentarer.

Bad example: The function takes a,b as input, calculates a + b, and returns the value.
Good example: The function returns the sum of a and b.

Att använda meningsfulla och beskrivande namn för variabler och funktionsnamn kan eliminera överflödiga kommentarer.

Kod först? Eller kommentera först? Att kommentera före kodning är bästa praxis; det vill säga skriv dina kommentarer och sedan motsvarande kod. På så sätt kan du först tänka på logiken och sedan konvertera den till kod.

# Returns true if the cnt is less than 1.
return cnt < 1

Använd ett konsekvent kommentarsformat som mellanrum, indrag, typ av kommentarer etc. för hela koden. Detta kommer att vara mindre förvirrande och mer organiserat för läsarna.

Använd docstrings för att förklara funktioner och klasser i Python som visas i följande exempel.

def add_num(a,b):
    """ this function returns the sum of a and b """
    sum = a+b
    return sum

Undvik onödiga kommentarer i din kod. Följande kodrad behöver till exempel ingen kommentar för att förstå den.

ans = 42

#1. Visual Studio Code Editor

Visual Studio Code Editor är den bästa IDE byggd av Microsoft för en komplett utvecklingsmiljö. Med inbyggt stöd för Node.js och JavaScript stöder verktyget även många andra programmeringsspråk sömlöst.

Detta mycket anpassningsbara verktyg har olika tillägg för olika funktioner. ”Bättre kommentarer” är ett sådant tillägg som låter dig skapa människovänliga kommentarer.

Du kan kategorisera dina kommentarer i varningar, frågor, höjdpunkter, etc., för enklare navigering.

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

Denna redigerare är tillgänglig på alla större plattformar som Mac, Windows och Linux.

#2. Sublim text

Sublim text är go-to editor för stora projekt och tung kodning. Redaktören är känd för sin hastighet, anpassning och genvägar.

Verktygets kraftfulla syntaxmarkeringsfunktion hjälper dig att enkelt skilja mellan koden och kommentarerna.

Liksom VS-kod, stöder Sublime text även redigering med flera markörer för att kommentera flera rader samtidigt.

Tack vare dess autokompletteringsfunktion. Du behöver inte upprepa kodraderna manuellt; den här funktionen kompletterar automatiskt din kod baserat på mönstren, vilket hjälper dig att koda snabbare.

Dessutom låter verktygets ”Goto Anything”-funktion dig sömlöst växla mellan funktionerna och filerna i ditt projekt.

#3. Anteckningar++

Nodepad++ är en populär och enkel textredigerare skriven i C++ och stöder många programmeringsspråk. Det ser inte ut som en modern redaktör som VS Code eller Sublime Text; dess gränssnitt är väldigt enkelt och ser ut som det gör vad det behöver.

Nodepad++ erbjuder många standardgenvägar för effektiv kommentar. Du kan också anpassa kortkommandot för att anpassa din kommentarsupplevelse.

Dess dokumentkartfunktion visar dig översikten över projektstrukturen, så att du kan navigera över filerna, mapparna och koden sömlöst.

#4. Vim

Vim IDE ger snabbare utveckling och kodexekvering. Allt och vad som helst kan göras på den här editorn med kortkommandon, så du bör anstränga dig ordentligt för att bemästra det.

Denna tangentbordscentrerade redigerare erbjuder också många kommentarsfunktioner via kortkommandon. Den har kraftfulla funktioner och kommandon för att effektivt navigera över kommentarer.

Denna lätta programvara kan hantera enorma filer och hundratals programmeringsspråk. Vem hatar gratissaker? Liksom alla redaktörer i listan är Vim också helt gratis och öppen källkod.

Det kommer inbyggt i macOS och Linux-system och är nedladdningsbart på Windows.

#5. PyCharm

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

Dessutom gör det att kommentera i Python mycket mer effektivt. Den tillhandahåller navigeringsfunktioner som hjälper dig att enkelt hoppa till specifika kommentarer.

Skaffa olika kommentarsmallar och skapa anpassade kommentarsmallar effektivt i Pycharm.

Dessutom låter redaktörens refaktoreringsverktyg dig enkelt uppdatera eller fixa kommentarer.

Slutsats

Att följa kodstandarder är nödvändigt under hela kodutvecklingsprocessen och obligatoriskt för att skriva produktionsfärdig kod, eftersom din kod bör vara läsbar av alla andra utvecklare och testare.

En viktig praxis för att skapa en läsbar kod är att skriva kommentarer. Kommentarer finns på nästan alla programmeringsspråk. Men med den här artikeln bör du nu veta hur du skriver Python-kommentarer, deras typer och de bästa metoderna att följa när du skriver kommentarer.

Dessutom listas de bästa kodredigerarna som hjälper dig med kommentarshantering.