Testele mai rapide din documentație cer un contract explicit

Testele din documentație merită accelerate atunci când exemplele continuă să dovedească ceea ce înțelege cititorul din ele. Remedierea compilării combinate din Rust, în martie 2025, oferă un motiv bun pentru a separa organizarea aleasă de compilator de contractul exemplului. Păstrați exemplele obișnuite eligibile pentru grupare și precizați cerințele excepționale de izolare. Oprirea îmbunătățirii peste tot ar pune costul câtorva presupuneri neobișnuite în sarcina tuturor exemplelor.

Privind din noiembrie 2026, Rust 1.85.0 a introdus ediția stabilă 2024 la 20 februarie 2025. Anunțul versiunii 1.85.1, din 18 martie, explică faptul că un defect al implementării trimisese testele combinate înapoi la vechea metodă, cu compilare separată. Versiunea de corecție a reparat comportamentul. Cronologia contează: o actualizare de corecție putea activa comportamentul prevăzut al ediției chiar dacă rulările anterioare păruseră neschimbate.

Compilarea și execuția au contracte separate

Un doctest este un exemplu de cod verificat de rustdoc. Compilarea separată a exemplelor repetă o parte din muncă. Gruparea exemplelor compatibile într-un executabil poate reduce acest cost. De aici nu rezultă că toate exemplele rulează într-un singur proces, în care variabilele statice ale unui exemplu afectează următorul.

Ghidul ediției, consultat în noiembrie 2026, separă explicit comportamentele: exemplele compatibile pot folosi același executabil compilat și pot rula în continuare în procese independente. Explicația actuală susține mecanismul; nu reprezintă o măsurătoare datată în martie. Distincția previne o reacție inutilă la migrare, construită în jurul unei presupuse execuții comune pe care schimbarea nu o introduce în general.

Separarea proceselor are și limite pe care gruparea compilării nu le poate rezolva. Două exemple executate independent pot accesa aceeași bază de date externă sau aceeași cale fixă de fișier. Resursele există în afara memoriei separate a proceselor. Proiectul are nevoie de reguli proprii pentru ele, indiferent cum organizează rustdoc executabilul.

Luați un manual ipotetic de bibliotecă, cu exemple aritmetice obișnuite și un exemplu despre poziția diagnosticelor în sursă. Primele urmăresc valorile returnate. Ultimul poate depinde de poziția sa în sursa generată. Tratarea lor identică ascunde presupunerea neobișnuită a celui din urmă și încurajează o soluție generală când numai un contract are nevoie de atenție.

Exemplul excepțional are nevoie de un motiv

Ghidul actual descrie excluderi automate, inclusiv exemplele compile_fail, etichetele explicite de ediție și anumite atribute globale sau aplicate întregului crate. Documentează și standalone_crate pentru exemplele care cer compilare separată, dar nu pot fi identificate automat. Comportamentele sensibile la poziția în sursă și căile de tip generate merită atenție când analizați eșecuri după migrare.

Sunt motive distincte pentru separare. Un exemplu care trebuie să eșueze la compilare nu poate fi tratat drept program obișnuit, compilat cu succes. Un exemplu al cărui sens depinde de structura unui crate poate cere unul separat, chiar dacă execuția ar fi altfel inofensivă. „Izolare” ar trebui să numească proprietatea necesară, nu să devină o etichetă pentru orice rezultat neașteptat.

Înainte de a adăuga o excepție, stabiliți dacă exemplul verifică API-ul public sau un detaliu incidental al infrastructurii de test. Dacă exemplul despre diagnostic promite o poziție exactă în documentație, compilarea separată poate fi justificată. Dacă un exemplu fără legătură compară doar o cale de tip dependentă de implementare, schimbarea acelei verificări poate exprima mai bine lecția dorită.

Aceasta este o decizie editorială și tehnică propusă, nu afirmația că exemplele vreunui proiect au fost reparate aici. Pentru articol nu s-a executat o compilare Rust sau un experiment de performanță. Anunțul stabilește remedierea istorică; numai evaluarea proiectului ar putea stabili îmbunătățirea locală de viteză și compatibilitatea.

Notați compilatorul și ediția

Versiunea compilatorului și ediția limbajului răspund unor întrebări diferite. Ansamblul de unelte instalat determină implementarea și remedierile disponibile. Ediția alege convențiile de limbaj și de unelte pentru crate. Dacă notați numai una dintre ele, un eșec poate deveni greu de reprodus, mai ales în jurul actualizării care a activat comportamentul prevăzut.

Pentru o migrare propusă, păstrați versiunea uneltelor, ediția crate-ului și exemplul care eșuează. Examinați dacă o compilare separată schimbă rezultatul relevant înainte de o excludere mai largă. Păstrați excepția lângă exemplu, astfel încât următorul dezvoltator să îi înțeleagă motivul fără să caute o discuție veche despre incident.

Și un exemplu care trece testul are nevoie de verificare din perspectiva cititorului. Pregătirea ascunsă poate face codul executabil, dar poate ascunde tocmai condiția de care utilizatorul are nevoie. Accelerarea verificărilor nu repară documentația înșelătoare. Examinați dacă partea vizibilă explică intrările necesare și dacă verificarea susține afirmația alăturată.

Beneficiul pentru firmă este un răspuns de încredere despre documentația folosită la integrarea bibliotecii. Așteptarea mai scurtă poate încuraja verificările frecvente, dar articolul nu estimează ore economisite. Un exemplu întreținut poate opri publicarea unei instrucțiuni greșite; valoarea depinde de integrarea reală și nu rezultă numai din anunțul compilatorului.

Compilarea separată poate rămâne alegerea potrivită

Obiecția cea mai puternică privește simplitatea. Un grup mic de exemple neobișnuite poate fi mai ușor de înțeles dacă fiecare are propriul crate, iar timpul de compilare poate să nu conteze în acel proiect. Compromisul poate fi bun când motivul este documentat și exemplele cer efectiv separarea mai puternică.

Limita este transformarea alegerii locale într-o regulă generală. Exemplele obișnuite nu ar trebui să preia o cerință excepțională fără motiv. Nici obiectivul de viteză nu ar trebui să determine autorul să elimine o verificare care exprimă un contract public real. Alegeți întâi verificarea, apoi organizarea execuției cu cel mai mic cost care o păstrează.

Pentru dezvoltare software la comandă, includeți exemplele documentației în predarea uneltelor. Notați compilatorul și ediția, păstrați excepțiile necesare vizibile și separați economiile la compilare de afirmațiile despre izolarea execuției. Migrarea utilă lasă o cale obișnuită mai rapidă și un motiv inteligibil pentru fiecare exemplu care cere altceva.