Cum să scrieți comentarii în Python pentru un cod curat și lizibil

Scrierea de comentarii bune în Python va permite altor dezvoltatori și testeri să citească și să înțeleagă codul cu ușurință.

Codul curat cu sintaxă consecventă, denumirea variabilelor descriptive și indentarea este ca prima carte, mai ușor de înțeles și de întreținut.

În plus, în zilele noastre, este mai puțin obișnuit ca o persoană să scrie codul complet pentru întreaga aplicație sau software; mai degrabă, o echipă sau un grup de oameni va lucra pentru același scop. În acest caz, codul curat și lizibil face colaborarea mai simplă și mai eficientă.

Dezvoltatorii și testerii își propun întotdeauna să implementeze software fără erori în producție. Scrierea unui cod curat și lizibil accelerează acest proces, făcând depanarea mai simplă și mai precisă. Deși găsiți unele erori în producție, codul mai curat este mai ușor de actualizat.

Mai important, codul curat și lizibil durează mai mult, deoarece codul rămâne proaspăt pe măsură ce timpul trece.

În cele din urmă, este esențial să aveți cod curat și ușor de citit pentru a crea software de lungă durată. Dar întrebarea este cum reușim exact asta? Ei bine, o metodă este utilizarea Comentarii.

Nu este frustrant când ai scris întregul cod pentru o logică complexă, dar a doua zi, când nu poți relua de unde ai rămas? Acest lucru nu se întâmplă când scrii comentarii.

Comentariile sunt un limbaj uman care explică ce face codul sursă. Le puteți scrie în orice limbă, de preferință în engleză, deoarece este o limbă globală.

Deci, ori de câte ori reveniți la codul sursă după zile sau chiar ani, comentariile vă vor explica ce ați scris cândva.

De asemenea, ajută alți dezvoltatori să vă înțeleagă cu ușurință codul. De aceea codul scris cu comentarii rămâne pentru totdeauna, chiar și în absența autorului său.

Mai mult decât atât, este destul de comun să ai conflicte atunci când ai de-a face cu diferite limbaje de programare, mai ales când lucrezi în echipă. Acolo vin comentariile în ajutor. Deși nu cunoașteți limbajul de programare al codului sursă scris de coechipierul dvs., comentariile vă ajută să înțelegeți logica din spatele acestuia.

Documentația codului este o modalitate mai cuprinzătoare de a vă menține codul sursă și permite echipei dvs. să colaboreze fără probleme. Conține totul despre cod, cum ar fi designul, funcționalitatea, arhitectura, componentele etc.,

Comentariile chiar contribuie la această documentație de cod. Comentariile bine scrise pot fi luate direct în documentația codului, astfel încât dezvoltatorii să înțeleagă nu numai ce și de ce, ci și cum codul dvs.

Comentariile nu doar citesc codul, ci vă ajută și să înțelegeți intenția dezvoltatorului din spatele fiecărei linii. Deci, dacă găsiți vreo eroare în viitor, veți ști unde să faceți exact actualizările de cod.
Puteți scrie comentarii ca un paragraf pentru întregul cod sau linii individuale explicând ce face fiecare bloc de cod. În acest fel, vă permit dvs. și alți dezvoltatori să înțelegeți bine codul, îmbunătățind lizibilitatea.
Comentariile pot împărți codul în secțiuni logice, simplificând navigarea prin cod.
Ar trebui să includeți comentarii care detaliază intrările, ieșirile și cazurile de utilizare așteptate, astfel încât un tester să vă poată citi codul.
În cele din urmă, introducerea unor comentarii bine scrise în documentația dvs. îmbunătățește lizibilitatea generală a documentației de cod.

5 jocuri de aventură bazate pe text pe care le puteți juca în browser

Comentariile în Python încep cu un simbol hash (#). Deci, atunci când începeți o linie cu hash (#), atunci orice lucru scris în acea linie este tratat ca un comentariu.

Când rulați codul, compilatorul ignoră linia care începe cu hash (#) ca și cum nici nu ar exista. Cu toate acestea, comentariile rămân vizibile în codul sursă pentru a-și îndeplini scopul.

Există trei tipuri principale.

Acestea sunt cele pe care le-ați văzut mai sus. Ele încep cu simbolul hash (#). Practic, linia care începe cu simbolul hash (#) este dedicată comentariului. Deci, Acesta se numește comentariu pe o singură linie, unde puteți scrie un comentariu doar într-o singură linie, începând cu hash (#).

Iată cum puteți scrie comentarii pe o singură linie

# This is single line comment.

Din punct de vedere tehnic, Python nu acceptă comentarii pe mai multe linii, dar există modalități de a realiza acest lucru în Python.

Puteți folosi hash (#) și pentru a scrie comentarii pe mai multe rânduri. Fiecare linie pe care o scrieți ar trebui să înceapă cu un simbol hash (#) aici.

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

Cuprins

#3. Python Docstrings

O modalitate populară de a scrie comentarii pe mai multe linii este de a folosi literale șir – „””….”””. Când scrieți ceva între ghilimele triple, compilatorul Python ignoră acele linii și execută partea rămasă din fișier.

Aceste comentarii se numesc docstrings atunci când sunt scrise imediat după funcții, module și clase.

Iată sintaxa pentru a face acest lucru

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

Scrierea de comentarii clare și detaliate vă îmbunătățește lizibilitatea și întreținerea codului. Deci, iată cele mai bune practici pentru comentarea clară în Python.

Cele mai bune aplicații pentru luarea de note pentru iPhone și iPad

Comentariile nu ar trebui să povestească doar ce face codul, ci ar trebui să reflecte scopul și intenția din spatele fiecărei linii.

Eliminați comentariile învechite și asigurați-vă că actualizați comentariile ori de câte ori modificați codul.

În loc de povești lungi, scrieți comentarii scurte și concrete.

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.

Utilizarea numelor semnificative și descriptive pentru variabile și nume de funcții poate elimina comentariile redundante.

Mai întâi codul? Sau comentezi mai intai? Comentarea înainte de codificare este cea mai bună practică; adică scrieți-vă comentariile și apoi codul corespunzător. În acest fel, vă puteți gândi mai întâi la logică și apoi o puteți converti în cod.

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

Utilizați un format de comentarii consistent, cum ar fi spațierea, indentarea, tipul de comentarii etc., pentru întregul cod. Acest lucru va fi mai puțin confuz și mai organizat pentru cititori.

Utilizați docstrings pentru a explica funcțiile și clasele în Python, așa cum se arată în exemplul următor.

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

Evitați comentariile inutile în codul dvs. De exemplu, următoarea linie de cod nu are nevoie de un comentariu pentru a o înțelege.

ans = 42

#1. Editor de cod Visual Studio

Editor de cod Visual Studio este cel mai bun IDE construit de Microsoft pentru un mediu de dezvoltare complet. Cu suport nativ pentru Node.js și JavaScript, instrumentul acceptă și multe alte limbaje de programare fără probleme.

Acest instrument extrem de personalizabil are diverse extensii pentru diferite funcționalități. „Comentarii mai bune” este o astfel de extensie care vă permite să creați comentarii prietenoase pentru oameni.

Vă puteți clasifica comentariile în alerte, interogări, evidențieri etc., pentru o navigare mai ușoară.

Codul VS acceptă editarea multi-cursor, astfel încât să puteți comenta sau edita mai multe rânduri simultan.

Acest editor este disponibil pe toate platformele majore precum Mac, Windows și Linux.

#2. Text sublim

Text sublim este editorul de bază pentru proiecte mari și codare grea. Editorul este cunoscut pentru viteza, personalizarea și comenzile rapide.

Funcția puternică de evidențiere a sintaxelor a instrumentului vă ajută să distingeți cu ușurință între cod și comentarii.

La fel ca și codul VS, textul Sublime acceptă și editarea multi-cursor pentru a comenta mai multe rânduri în același timp.

Datorită funcției de completare automată. Nu trebuie să repetați manual liniile de cod; această caracteristică completează automat codul pe baza tiparelor, ajutându-vă să codificați mai rapid.

Cele mai bune și eficiente puncte de acces wireless (WAP) pentru 2022

În plus, funcția „Goto Anything” a instrumentului vă permite să comutați fără probleme între funcțiile și fișierele proiectului.

#3. Notepad++

Nodepad++ este un editor de text popular și simplu scris în C++ și acceptă numeroase limbaje de programare. Nu arată ca un editor modern precum VS Code sau Sublime Text; interfața sa este foarte simplă și pare că face ceea ce trebuie.

Nodepad++ oferă numeroase comenzi rapide standard pentru comentarii eficiente. De asemenea, puteți personaliza tastatura de comenzi rapide pentru a vă personaliza experiența de comentare.

Caracteristica sa de hartă a documentelor vă arată o privire de ansamblu asupra structurii proiectului, permițându-vă să navigați fără probleme peste fișiere, foldere și cod.

#4. Vim

Vim IDE oferă o dezvoltare mai rapidă și execuție de cod. Totul și orice se poate face cu acest editor folosind comenzi rapide de la tastatură, așa că ar trebui să depuneți un efort serios pentru a-l stăpâni.

Acest editor centrat pe tastatură oferă, de asemenea, multe funcții de comentare prin comenzile rapide de la tastatură. Are funcții și comenzi puternice pentru a naviga eficient peste comentarii.

Acest software ușor poate gestiona fișiere uriașe și sute de limbaje de programare. Cine urăște lucrurile gratuite? La fel ca toți editorii din listă, Vim este, de asemenea, complet gratuit și open source.

Vine nativ în sistemele macOS și Linux și poate fi descărcat pe Windows.

#5. PyCharm

PyCharm este un IDE puternic care este special conceput pentru dezvoltarea Python. Deși acceptă multe alte limbaje de programare, funcționează cel mai bine pentru Python. Are funcții de completare a codului, evidențiere a sintaxelor și depanare adaptate pentru Python.

În plus, face comentariile în Python mult mai eficiente. Oferă funcții de navigare pentru a vă ajuta să treceți cu ușurință la anumite comentarii.

Obțineți diferite șabloane de comentarii și creați șabloane de comentarii personalizate eficient în Pycharm.

De asemenea, instrumentele de refactorizare ale editorului vă permit să actualizați sau să remediați cu ușurință comentariile.

Concluzie

Respectarea standardelor de cod este necesară pe parcursul întregului proces de dezvoltare a codului și este obligatorie pentru a scrie cod gata de producție, deoarece codul dvs. ar trebui să fie citit de toți ceilalți dezvoltatori și testeri.

O practică importantă pentru a crea un cod care poate fi citit este scrierea de comentarii. Comentariile sunt disponibile în aproape toate limbajele de programare. Cu toate acestea, cu acest articol, ar trebui să știți acum cum să scrieți comentarii Python, tipurile acestora și cele mai bune practici de urmat în timp ce scrieți comentarii.

De asemenea, cele mai bune editori de cod care vă ajută în gestionarea comentariilor sunt enumerate mai jos.