Hvordan skrive kommentarer i Python for ren og lesbar kode

Å skrive gode kommentarer i Python vil tillate andre utviklere og testere å lese og forstå koden din enkelt.

Ren kode med konsekvent syntaks, beskrivende variabelnavn og innrykk er som den første boken, enklere å forstå og vedlikeholde.

I tillegg er det i disse dager mindre vanlig for en person å skrive hele koden for hele applikasjonen eller programvaren; snarere vil et team eller en gruppe mennesker jobbe mot det samme målet. I dette tilfellet gjør ren og lesbar kode samarbeid enklere og mer effektivt.

Utviklere og testere har alltid som mål å distribuere feilfri programvare til produksjon. Å skrive ren og lesbar kode akselererer denne prosessen ved å gjøre feilsøking enklere og mer nøyaktig. Selv om du finner noen feil i produksjonen, er renere kode enklere å oppdatere.

Enda viktigere, ren og lesbar kode lever lenger fordi koden forblir fersk etter hvert som tiden går.

Til slutt er det avgjørende å ha ren og lesbar kode for å lage langvarig programvare. Men spørsmålet er, hvordan skal vi oppnå det? Vel, en metode er å bruke kommentarer.

Er det ikke frustrerende når du har skrevet hele koden for en kompleks logikk, men dagen etter, når du ikke kan fortsette der du slapp? Dette skjer ikke når du skriver kommentarer.

Kommentarer er et menneskelig språk som forklarer hva kildekoden gjør. Du kan skrive dem på et hvilket som helst språk, helst engelsk, siden det er et globalt språk.

Så når du kommer tilbake til kildekoden din etter dager eller til og med år, vil kommentarene forklare deg hva du en gang skrev.

Dessuten hjelper de andre utviklere med å enkelt forstå koden din. Det er derfor koden skrevet med kommentarer forblir for alltid, selv i fravær av forfatteren.

Dessuten er det ganske vanlig å ha konflikter når du arbeider med forskjellige programmeringsspråk, spesielt når du jobber i et team. Det er der kommentarer kommer til unnsetning. Selv om du ikke kan programmeringsspråket til kildekoden skrevet av lagkameraten din, hjelper kommentarer deg å forstå logikken bak det.

Kodedokumentasjon er en mer omfattende måte å vedlikeholde kildekoden på og lar teamet ditt samarbeide sømløst. Den inneholder alt om koden, som design, funksjonalitet, arkitektur, komponenter, etc.,

Kommentarer bidrar til og med til denne kodedokumentasjonen. Velskrevne kommentarer kan tas direkte inn i kodedokumentasjonen slik at utviklere ikke bare får hva og hvorfor, men også hvordan koden din.

• Kommentarer leser ikke bare opp koden, men hjelper deg også å forstå utviklerens hensikt bak hver linje. Så hvis du finner en feil i fremtiden, vet du nøyaktig hvor du skal gjøre kodeoppdateringene.
• Du kan skrive kommentarer som et avsnitt for hele koden eller individuelle linjer som forklarer hva hver kodeblokk gjør. På denne måten lar de deg og andre utviklere forstå koden godt, noe som forbedrer lesbarheten.
• Kommentarer kan dele koden inn i logiske deler, noe som gjør kodenavigering enklere.
• Du bør inkludere kommentarer som beskriver forventede innganger, utganger og brukstilfeller slik at en tester kan lese koden din.
• Til slutt, å legge inn velskrevne kommentarer i dokumentasjonen forbedrer den generelle lesbarheten til kodedokumentasjonen.

Kommentarer i Python begynner med et hash-symbol (#). Så når du starter en linje med hash (#), så behandles alt som er skrevet på den linjen som en kommentar.

Når du kjører koden, ignorerer kompilatoren linjen som starter med hash (#) som om den ikke engang eksisterer. Kommentarene forblir imidlertid synlige i kildekoden for å tjene deres formål.

Det er tre hovedtyper.

Dette er de du har sett ovenfor. De starter med hash-symbolet (#). I utgangspunktet er linjen som begynner med hash-symbolet (#) dedikert til kommentaren. Så dette kalles en enkeltlinjekommentar, der du kan skrive en kommentar bare på én linje som starter med hash (#).

Slik kan du skrive enlinjekommentarer

# This is single line comment.

Teknisk sett støtter ikke Python flerlinjekommentarer, men det finnes måter å oppnå dette på i Python.

Du kan også bruke hash (#) for å skrive kommentarer med flere linjer. Hver linje du skriver skal starte med et hash-symbol (#) her.

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

#3. Python Docstrings

En populær måte å skrive kommentarer på flere linjer er å bruke bokstaver i strenger – «»»….»»». Når du skriver noe mellom tredoble anførselstegn, ignorerer Python-kompilatoren disse linjene og kjører den gjenværende delen i filen.

Disse kommentarene kalles docstrings når de er skrevet rett etter funksjonene, modulene og klassene.

Her er syntaksen for å gjøre dette

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

Å skrive klare og detaljerte kommentarer forbedrer kodens lesbarhet og vedlikehold. Så her er de beste fremgangsmåtene for tydelige kommentarer i Python.

Kommentarer skal ikke bare fortelle hva koden gjør, i stedet skal de gjenspeile formålet og intensjonen bak hver linje.

Fjern utdaterte kommentarer, og sørg for å oppdatere kommentarer hver gang du endrer koden.

I stedet for lange historier, skriv korte og konkrete 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.

Bruk av meningsfylte og beskrivende navn for variabler og funksjonsnavn kan eliminere overflødige kommentarer.

Kode først? Eller kommentere først? Å kommentere før koding er den beste praksisen; det vil si, skriv kommentarene dine og deretter den tilsvarende koden. På denne måten kan du først tenke på logikken og deretter konvertere den til kode.

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

Bruk et konsistent kommentarformat som mellomrom, innrykk, type kommentarer osv. for hele koden. Dette vil være mindre forvirrende og mer organisert for leserne.

Bruk docstrings for å forklare funksjoner og klasser i Python som vist i følgende eksempel.

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

Unngå unødvendige kommentarer i koden din. Følgende kodelinje trenger for eksempel ikke en kommentar for å forstå den.

ans = 42

#1. Visual Studio Code Editor

Visual Studio Code Editor er den beste IDE bygget av Microsoft for et komplett utviklingsmiljø. Med innebygd støtte for Node.js og JavaScript, støtter verktøyet også mange andre programmeringsspråk sømløst.

Dette svært tilpassbare verktøyet har forskjellige utvidelser for forskjellige funksjoner. «Bedre kommentarer» er en slik utvidelse som lar deg lage menneskevennlige kommentarer.

Du kan kategorisere kommentarene dine i varsler, forespørsler, høydepunkter osv. for enklere navigering.

VS-kode støtter redigering med flere markører slik at du kan kommentere eller redigere flere linjer samtidig.

Denne editoren er tilgjengelig på alle større plattformer som Mac, Windows og Linux.

#2. Sublim tekst

Sublim tekst er den beste redaktøren for store prosjekter og tung koding. Redaktøren er kjent for sin hastighet, tilpasning og snarveier.

Verktøyets kraftige syntaksuthevingsfunksjon hjelper deg enkelt å skille mellom koden og kommentarer.

Som VS-kode, støtter Sublime-tekst også redigering av flere markører for å kommentere flere linjer samtidig.

Takket være autofullføringsfunksjonen. Du trenger ikke å gjenta kodelinjene manuelt; denne funksjonen fullfører koden din automatisk basert på mønstrene, og hjelper deg med å kode raskere.

Dessuten lar verktøyets «Goto Anything»-funksjon deg bytte sømløst mellom funksjonene og filene til prosjektet ditt.

#3. Notisblokk++

Nodepad++ er en populær og enkel tekstredigerer skrevet i C++ og støtter en rekke programmeringsspråk. Det ser ikke ut som en moderne editor som VS Code eller Sublime Text; grensesnittet er veldig enkelt og ser ut som det gjør det det skal.

Nodepad++ tilbyr en rekke standard snarveier for effektiv kommentering. Du kan også tilpasse snarveistastaturet for å tilpasse kommentaropplevelsen din.

Dokumentkartfunksjonen viser deg oversikten over prosjektstrukturen, slik at du kan navigere sømløst over filene, mappene og koden.

#4. Vim

Vim IDE gir raskere utvikling og kodeutførelse. Alt og hva som helst kan gjøres på denne editoren ved å bruke hurtigtaster, så du bør legge en seriøs innsats i å mestre det.

Denne tastatursentriske editoren tilbyr også mange kommentarfunksjoner via hurtigtaster. Den har kraftige funksjoner og kommandoer for å effektivt navigere over kommentarer.

Denne lette programvaren kan håndtere enorme filer og hundrevis av programmeringsspråk. Hvem hater gratis ting? Som alle redaktørene på listen, er Vim også helt gratis og åpen kildekode.

Den kommer innfødt i macOS- og Linux-systemer og kan lastes ned på Windows.

#5. PyCharm

PyCharm er en kraftig IDE som er spesialdesignet for Python-utvikling. Selv om det støtter mange andre programmeringsspråk, fungerer det best for Python. Den har kodefullføring, syntaksutheving og feilsøkingsfunksjoner skreddersydd for Python.

Dessuten gjør det kommentering i Python mye mer effektivt. Den har navigasjonsfunksjoner som hjelper deg enkelt å hoppe til spesifikke kommentarer.

Få ulike kommentarmaler og lag tilpassede kommentarmaler effektivt i Pycharm.

I tillegg lar redaktørens refactoring-verktøy deg enkelt oppdatere eller fikse kommentarer.

Konklusjon

Å følge kodestandarder er nødvendig gjennom hele kodeutviklingsprosessen og obligatorisk for å skrive produksjonsklar kode, da koden din skal kunne leses av alle andre utviklere og testere.

En viktig praksis for å lage en lesbar kode er å skrive kommentarer. Kommentarer er tilgjengelig på nesten alle programmeringsspråk. Men med denne artikkelen bør du nå vite hvordan du skriver Python-kommentarer, deres typer og de beste fremgangsmåtene du bør følge mens du skriver kommentarer.

Dessuten er de beste koderedigererne som hjelper deg med kommentarbehandling listet opp.