Creați comentarii Python în mod corect

Comentariile sunt note pe care programatorii își anunță codul pentru a explica ce ar trebui să facă acel cod. Compilatorii sau interpreții care transformă codul în acțiune ignoră comentariile, dar acestea pot fi esențiale pentru gestionarea proiectelor software.

Comentariile vă ajută să explicați codul dvs. Python altor programatori și vă pot aminti de ce ați făcut alegerile pe care le-ați făcut. Comentariile facilitează depanarea și revizuirea codului, ajutând viitorii programatori să înțeleagă alegerile de proiectare din spatele software-ului.

Deși comentariile sunt în primul rând pentru dezvoltatori, scrierea unora eficiente poate ajuta, de asemenea, la producerea unei documentații excelente pentru utilizatorii codului dvs. Cu ajutorul generatoarelor de documente precum Sphinx pentru proiectele Python, comentariile din codul dvs. pot furniza conținut pentru documentația dvs.

Să ne uităm sub capota de a comenta în Python.

Comentarii în Python

Conform Ghidului de stil Python PEP 8, există câteva lucruri de care trebuie să țineți cont atunci când scrieți comentarii:

• Comentariile ar trebui să fie întotdeauna propoziții complete și concise.
• Este mai bine să nu ai niciun comentariu decât unul greu de înțeles sau inexact.
• Comentariile ar trebui să fie actualizate în mod regulat pentru a reflecta modificările din codul dvs.
• Prea multe comentarii pot distrage atenția și pot reduce calitatea codului. Comentariile nu sunt necesare acolo unde scopul codului este evident.

În Python, o linie este declarată ca comentariu atunci când începe cu simbolul # . Când interpretul Python întâlnește # în codul dvs., ignoră orice după acel simbol și nu produce nicio eroare. Există două moduri de a declara comentarii pe o singură linie: comentarii inline și comentarii bloc.

Comentarii în linie

Comentariile inline oferă scurte descrieri ale variabilelor și operațiunilor simple și sunt scrise pe aceeași linie ca instrucțiunea de cod:

 border = x + 10 # Make offset of 10px

Comentariul explică funcția codului în aceeași declarație ca și codul.

Blocați comentariile

Comentariile de bloc sunt folosite pentru a descrie logica complexă în cod. Comentariile bloc în Python sunt construite în mod similar cu comentariile inline - singura diferență este că comentariile bloc sunt scrise pe o linie separată:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

Rețineți că atunci când utilizați comentarii bloc, comentariile sunt scrise deasupra codului pe care îl explică. Ghidul de stil Python PEP8 dictează că o linie de cod nu trebuie să conțină mai mult de șaptezeci și nouă de caractere, iar comentariile în linie împing adesea linii peste această lungime. Acesta este motivul pentru care comentariile de bloc sunt scrise pentru a descrie codul pe rânduri separate.

Comentarii pe mai multe rânduri

Python nu acceptă în mod nativ comentariile pe mai multe rânduri, ceea ce înseamnă că nu există o prevedere specială pentru definirea lor. În ciuda acestui fapt, comentariile care se întind pe mai multe rânduri sunt adesea folosite.

Puteți crea un comentariu pe mai multe rânduri din mai multe comentarii pe o singură linie, prefațând fiecare rând cu # :

 # interpreter # ignores # these lines

De asemenea, puteți utiliza sintaxa șirurilor cu mai multe linii. În Python, puteți defini șiruri cu mai multe rânduri încadrându-le în """ , ghilimele duble triple sau ''' , ghilimele simple triple:

 print("Multi-Line Comment") """ This String is Multi line """

În codul de mai sus, șirul cu mai multe linii nu este atribuit unei variabile, ceea ce face ca șirul să funcționeze ca un comentariu. La runtime, Python ignoră șirul și nu este inclus în bytecode. Executarea codului de mai sus produce următoarea ieșire:

 Multi-Line Comment

Comentarii speciale

Pe lângă faptul că vă fac codul lizibil, comentariile servesc și unor scopuri speciale în Python, cum ar fi planificarea adăugărilor viitoare de cod și generarea de documentație.

Comentarii Python Docstring

În Python, docstring-urile sunt comentarii pe mai multe rânduri care explică cum să folosești o anumită funcție sau clasă. Documentația codului dvs. este îmbunătățită prin crearea de documente de înaltă calitate. În timp ce lucrați cu o funcție sau clasă și folosiți funcția încorporată help(obj) , documentele ar putea fi utile pentru a oferi o imagine de ansamblu asupra obiectului.

Python PEP 257 oferă o metodă standard de declarare a documentelor în Python, prezentată mai jos:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

În codul de mai sus, documentul a furnizat detalii despre cum funcționează funcția asociată. Cu generatoare de documentație precum Sphinx, acest șir de documente poate fi folosit pentru a oferi utilizatorilor proiectului dvs. o privire de ansamblu asupra modului de utilizare a acestei metode.

Un șir de document definit chiar sub semnătura funcției sau a clasei poate fi returnat și folosind funcția încorporată help() . Funcția help() ia un obiect sau un nume de funcție ca argument și returnează șirurile de documente ale funcției ca ieșire. În exemplul de mai sus, help(get_person) poate fi apelat pentru a dezvălui documente asociate cu funcția get_person . Dacă rulați codul de mai sus într-un shell interactiv folosind steag-ul -i , puteți vedea cum acest șir documentar va fi analizat de Python. Rulați codul de mai sus tastând python -i file.py .

Apelul funcției help(get_person) returnează un șir documentar pentru funcția dvs. Ieșirea conține get_person(name, age, d=False) , care este o semnătură a funcției pe care Python o adaugă automat.

get_person.__ doc__ poate fi, de asemenea, utilizat pentru a prelua și modifica docstrings în mod programatic. După ce ați adăugat „Alte informații noi” în exemplul de mai sus, aceasta apare în al doilea apel de help(get_person) . Totuși, este puțin probabil să fie nevoie să modificați dinamic șirurile de documente în timpul rulării astfel.

TODO Comentarii

Când scrieți cod, există ocazii când veți dori să evidențiați anumite linii sau blocuri întregi pentru îmbunătățire. Aceste sarcini sunt semnalate de comentariile TODO. Comentariile TODO sunt utile atunci când planificați actualizări sau modificări ale codului dvs. sau dacă doriți să informați utilizatorii sau colaboratorii proiectului că anumite secțiuni ale codului fișierului rămân de scris.

Comentariile TODO nu trebuie scrise ca pseudocod - trebuie doar să explice pe scurt funcția codului încă nescris.

Comentariile TODO și comentariile bloc cu o singură linie sunt foarte asemănătoare și singura distincție între ele este că comentariile TODO trebuie să înceapă cu un prefix TODO:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

Este important de reținut că, deși multe IDE-uri pot evidenția aceste comentarii pentru programator, interpretul Python nu vede comentariile TODO în mod diferit față de comentariile de bloc.

Cele mai bune practici atunci când scrieți comentarii Python

Există o serie de bune practici care ar trebui urmate atunci când scrieți comentarii pentru a asigura fiabilitatea și calitatea. Mai jos sunt câteva sfaturi pentru a scrie comentarii de înaltă calitate în Python.

Evitați ceea ce este evident

Comentariile care afirmă ceea ce este evident nu adaugă nicio valoare codului tău și ar trebui evitate. De exemplu:

 x = x + 4 # increase x by 4

Acest comentariu nu este util, deoarece spune pur și simplu ce face codul fără a explica de ce trebuie făcut. Comentariile ar trebui să explice „de ce” mai degrabă decât „ce” din codul pe care îl descriu.

Rescris mai util, exemplul de mai sus ar putea arăta astfel:

 x = x + 4 # increase the border width

Păstrați comentariile Python scurte și dulci

Păstrați-vă comentariile scurte și ușor de înțeles. Ele ar trebui să fie scrise în proză standard, nu în pseudocod și ar trebui să înlocuiască necesitatea de a citi codul real pentru a obține o imagine generală a ceea ce face. Prea multe detalii sau comentarii complexe nu ușurează munca unui programator. De exemplu:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Comentariul de mai sus oferă mai multe informații decât este necesar pentru cititor. În loc să specifice logica de bază, comentariile ar trebui să ofere un rezumat general al codului. Acest comentariu poate fi rescris ca:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Utilizați identificatorii cu atenție

Identificatorii trebuie folosiți cu atenție în comentarii. Schimbarea numelor de identificare sau a cazurilor poate deruta cititorul. Exemplu:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

Comentariul de mai sus menționează class și argument , niciunul dintre acestea nu se găsește în cod. Acest comentariu poate fi rescris ca:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

USCAT și UME

Când scrieți cod, doriți să respectați principiul DRY (nu vă repetați) și să evitați WET (scrieți totul de două ori).

Acest lucru este valabil și pentru comentarii. Evitați să folosiți mai multe instrucțiuni pentru a vă descrie codul și încercați să îmbinați comentariile care explică același cod într-un singur comentariu. Cu toate acestea, este important să fiți atenți când îmbinați comentarii: îmbinarea neglijentă a mai multor comentarii poate duce la un comentariu imens care încalcă ghidurile de stil și este dificil de urmat de către cititor.

Rețineți că comentariile ar trebui să reducă timpul de citire a codului.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

În codul de mai sus, comentariile sunt fragmentate în mod inutil și pot fi îmbinate într-un singur comentariu:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

Indentare consecventă

Asigurați-vă că comentariile sunt indentate la același nivel cu codul pe care îl descriu. Când nu sunt, pot fi dificil de urmărit.

De exemplu, acest comentariu nu este indentat sau poziționat corect:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

Poate fi rescris astfel:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

rezumat

Comentariile sunt o componentă importantă a scrierii unui cod ușor de înțeles. Investiția pe care o faci în scrierea unui comentariu este una pe care viitorul tău personal - sau alți dezvoltatori care trebuie să lucreze la baza ta de cod - o vor aprecia. Comentarea vă permite, de asemenea, să obțineți informații mai profunde asupra codului dvs.

În acest tutorial, ați învățat mai multe despre comentarii în Python, inclusiv despre diferitele tipuri de comentarii Python, când să utilizați fiecare dintre ele și cele mai bune practici de urmat la crearea acestora.

A scrie comentarii bune este o abilitate care trebuie studiată și dezvoltată. Pentru a exersa scrierea comentariilor, luați în considerare să reveniți și să adăugați comentarii la unele dintre proiectele dvs. anterioare. Pentru inspirație și pentru a vedea cele mai bune practici în acțiune, consultați proiecte Python bine documentate pe GitHub.

Când sunteți gata să vă creați propriile proiecte Python live, platforma de găzduire a aplicațiilor Kinsta vă poate duce codul din GitHub în cloud în câteva secunde.