Cum folosești GitHub Copilot pentru documentarea codului, explicarea funcțiilor și scrierea testelor simple

GitHub Copilot poate reduce timpul petrecut încercând să înțelegi un proiect existent, scriind comentarii repetitive sau pregătind primele teste unitare. Rezultatele sunt însă utile doar dacă îi oferi codul potrivit ca context și verifici fiecare explicație sau test înainte să îl introduci în proiect.

Pentru acest tutorial folosim GitHub Copilot Chat într-un IDE compatibil, precum Visual Studio Code, Visual Studio sau un IDE JetBrains. Ai nevoie de acces la GitHub Copilot și de extensia corespunzătoare instalată în editor. GitHub precizează că Copilot poate genera teste de bază eficient, dar scenariile complexe cer instrucțiuni mai detaliate și verificare suplimentară.

Înțelege funcția înainte să o documentezi

Deschide proiectul și fișierul care conține funcția. Selectează doar funcția relevantă, nu întregul fișier de câteva sute de linii. Apoi deschide Copilot Chat și scrie:

Explică această funcție în limba română.

Include:
- ce primește;
- ce returnează;
- ce verificări face;
- ce erori poate produce;
- ce efecte secundare are;
- ce cazuri-limită observi.

Nu modifica încă codul.

GitHub recomandă deschiderea fișierului sau selectarea liniilor relevante pentru a oferi context. Pe GitHub.com, poți selecta liniile și deschide Copilot Chat direct lângă selecție; în IDE poți păstra fișierul activ sau atașa explicit fișierele necesare.

Nu accepta explicația dacă nu poți confirma traseul codului. Verifică funcțiile apelate, valorile returnate și eventualele modificări făcute în baze de date, fișiere sau variabile globale. Copilot poate explica convingător o presupunere greșită.

Pentru o funcție care depinde de alte fișiere, adaugă contextul exact:

Analizează funcția selectată împreună cu fișierele de validare și configurare atașate.

Explică traseul unei cereri de la intrare până la rezultat.
Menționează clar ce informații nu pot fi confirmate din fișierele disponibile.

Generează documentație care spune ceva util

După ce ai înțeles funcția, cere documentația în formatul folosit de proiect. Pentru JavaScript sau TypeScript poți solicita JSDoc:

Adaugă un comentariu JSDoc pentru funcția selectată.

Documentează:
- scopul real;
- fiecare parametru și tipul lui;
- valoarea returnată;
- excepțiile posibile;
- un exemplu scurt de utilizare.

Nu descrie fiecare linie și nu inventa comportamente.
Nu modifica implementarea.

Pentru Python, cere un docstring în stilul deja folosit în repository. Pentru PHP, solicită PHPDoc. GitHub include documentarea codului, explicarea logicii complexe și sincronizarea documentației cu schimbările de cod printre utilizările recomandate pentru Copilot Chat.

Comentariile bune explică motivul unei decizii sau contractul funcției. Evită rezultate precum:

// Verifică dacă utilizatorul există
if (user) {

Comentariul doar repetă codul. Mai valoros ar fi:

// Conturile dezactivate rămân în bază pentru audit,
// dar nu pot iniția o sesiune nouă.

Compară documentația generată cu implementarea. Dacă funcția acceptă null, dar documentația spune că primește întotdeauna un obiect, corectează textul înainte de commit.

Scrie primele teste unitare

Selectează funcția și folosește comanda /tests. Poți preciza framework-ul și comportamentele importante:

/tests using Jest

Creează teste pentru funcția selectată.

Acoperă:
- cazul valid;
- valoare lipsă;
- valoare cu tip greșit;
- limita minimă;
- limita maximă;
- eroarea așteptată.

Nu modifica funcția testată.
Folosește stilul testelor existente în proiect.

GitHub documentează comanda /tests pentru fișierul activ sau codul selectat și permite completarea cererii cu framework-ul și cazurile care trebuie verificate.

Nu insera imediat fișierul generat. Verifică importurile, numele funcției, framework-ul, configurația proiectului și valorile așteptate. Un test poate trece și totuși să verifice comportamentul greșit.

Rulează doar fișierul nou, apoi întreaga suită:

npm test -- userValidator.test.js
npm test

Comanda exactă depinde de proiect. Dacă un test eșuează, nu cere direct Copilot să modifice aplicația. Întreabă mai întâi:

Explică de ce acest test eșuează.

Separă:
- posibilă problemă în test;
- posibilă problemă în implementare;
- informații lipsă.

Nu modifica niciun fișier.

Pentru rezultate mai coerente, poți adăuga în repository fișierul .github/copilot-instructions.md, în care specifici framework-ul de testare, convențiile proiectului și comenzile de validare. GitHub arată că instrucțiunile de repository îi oferă Copilot context despre cum trebuie înțeles, construit și testat proiectul.

Nu introduce în chat parole, chei API, tokenuri, date reale ale clienților sau configurații sensibile. Înainte de commit, verifică diferențele din Git, rulează testele și citește documentația ca și cum ar urma să fie folosită de un coleg nou. Copilot poate produce prima variantă. Responsabilitatea pentru corectitudinea codului și a testelor rămâne la dezvoltator.

Surse folosite

GitHub Docs – Using GitHub Copilot to explore a codebase
GitHub Docs – Document code
GitHub Docs – Getting started with prompts for GitHub Copilot Chat in your IDE
GitHub Docs – Writing tests with GitHub Copilot
GitHub Docs – Adding repository custom instructions for GitHub Copilot
GitHub Docs – Responsible use of GitHub Copilot features