Istoria Modificarea într-un fișier

voturi
2

Am lucrat câteva locuri care nu au utilizat controlul sursei. Ei păreau să intre în obiceiul de a pune comentarii în jurul valorii de cod au schimbat explica schimbarea, astfel că lucrurile ar putea fi inversat.

Am constatat că acest lucru face codul foarte greu de citit, și au fost destul de neînduplecați că aceste comentarii nu sunt necesare după introducerea controlului sursei ca istoricul de revizuire va permite să vă potrivi bilete cu modificări.

Cu toate acestea acum, eu nu sunt atât de sigur, cred că poate fi bun pentru a documenta revizuiri majore într-un fișier într-un fișier precum și în mesajele comit. Acest lucru ar trebui să facă codul mai ușor de citit. Oamenii au cel mai bun mod de practici de documentare a modificărilor aduse codului, astfel încât nu este prea aglomerat, dar este încă o explicație în cineva care încearcă să-l citească?

Doar să fie clar, eu nu vorbesc despre o listă a modificărilor în capul fișierului (care este un alt argument întreg), dar comentarii în cod.

Întrebat 12/03/2009 la 13:38
sursa de către utilizator
În alte limbi...                            


8 răspunsuri

voturi
5

Cele mai multe sisteme de control sursă au un „Adnotați“ sau „vina“ de comandă. Ea arată ce cod schimbat cu fiecare revizuire.

Deoarece aceste informații nu schimbă comportamentul programului, sau de a face mai ușor de înțeles programul, nu face parte din program.

Publicat 12/03/2009 la 13:45
sursa de către utilizator

voturi
0

Cred că este bine să se documenteze schimbări majore sau refactorings ca comentarii în cod. Sunt de acord că nu obține un pic murdar pentru a citi în jurul valorii de cantități mari de comentarii, dar cred că este destul de ușor pentru a ignora comentariile și să încerce să citească doar codul. Dacă ceva este confuz, sau ești tentat să schimbe ceva, și există un comentariu în apropiere, vei fi mult mai înclinați să citească comentariul, spre deosebire de a face diff cu versiunile anterioare pentru a vedea ce sa schimbat și de ce.

Publicat 12/03/2009 la 13:45
sursa de către utilizator

voturi
3

Documentația prezentă în cod trebuie să descrie codul este aproape. În cazul în care codul se schimbă, de asemenea, documentația trebuie să se schimbe în mod corespunzător. Sistemul de control al versiunii ar trebui să aibă grijă de gestionare a ceea ce sa schimbat și de ce sa schimbat. Lăsați codul și este documentația faci este treaba (Fac lucruri, și descrie cum / de ce se fac aceste lucruri), și lăsați sistemul de control al versiunii face este treaba (controlul / versiuni documentare și modificări).

De fiecare dată când începe să indice istorie în prezent (cod curent), vi se cere probleme. Gândește-te cum ar arăta o zonă deosebit schimba-grele de cod cum ar fi în cazul în care acesta a avut o serie de modificări ?!

Publicat 12/03/2009 la 13:46
sursa de către utilizator

voturi
1

Nu cred că comentare schimbări în interiorul unui cod este întotdeauna posibil, într-un mod explicativ.

Dar aș vrea să spun despre „istoria Modificarea la fișierul începe“. Mă îndoiesc că acest lucru este util la toate. Doar dacă am vrut să știu ce la versiuni ale unui fișier pentru a compara pentru a vedea diferența că au fost introduse cu o anumită sarcină „NNNN“. În fișierul începe există o linie „data NNNN - descriere mică“. Și controlul nostru sursă poate „spune“ cine și în ce versiune a fost introdusă această linie.
Deci , fără această linie , aș uita prin toate versiunile pentru a găsi unul corect.

Publicat 12/03/2009 la 13:46
sursa de către utilizator

voturi
3

În cazul în care comentariul este timpul sensibil nu o fac este o idee proastă. Pune un comentariu la fișierul sursă din sistemul de control al versiunii în loc.

Văd această problemă tot timpul la locul de muncă. Baza de cod sunt în prezent de lucru pe extinde înapoi în 1979. Vă puteți imagina dificultatea cu comentarii, cum ar fi cea de mai jos, care au construit peste acel moment:

„Linia de mai jos pare a repara bug xyz, va reveni în cazul în care apar probleme neprevăzute“

Îmi dau seama că nu este un comentariu foarte descriptiv, în primul rând, dar acest tip de lucru în SVN / cvs / etc. este de fapt foarte la îndemână. Un comentariu de genul asta în codul seamănă semințele îndoielii. Poate fi eliminat comentariu? Este problema care a cauzat neprevăzute să mă trebuie să se uite înapoi la codul de legătură cu acest comentariu? etc.

Publicat 12/03/2009 la 13:51
sursa de către utilizator

voturi
0

Fiecare metodă în codebase noastră are propria sa istorie de schimbare. Atunci când codul unei metode este schimbat antetul devine o nouă intrare. Codul în sine nu ajunge aglomerat cu comentarii istorie, doar antetul metodei. Fiecare intrare istoric al modificărilor constă din una sau două linii care descriu pe scurt motivul pentru schimbarea codului în termeni generali. Intrarea conține, de asemenea, un număr care se referă la un document de schimbare, schimbare Documentul conține, de asemenea, link-uri către rapoarte de erori, proiecte de dezvoltare, documente de proiectare etc.

Aceste intrări sunt de neprețuit, deoarece de multe ori a vă oferi o perspectivă cu privire la motivele pentru care codul este așa cum este. Dacă sunteți acolo pentru a repara un bug linia de istorie va spune invariabil ce schimbarea codului introdus bug-ul, ceea ce schimbarea a fost încercarea de a face, și, prin urmare, ce altceva trebuie să fie conștienți de atunci când decide cu privire la un fix.

OTOH - Reams de comentarii în corpul codului care descrie ceea ce face și cine-a schimbat atunci când sunt doar zgomot.

Publicat 12/03/2009 la 14:47
sursa de către utilizator

voturi
2

Mă întrebam cum să știe ce programul folosit pentru a face ajută la înțelegerea acum? Ai spune că ajută lizibilitatea. Cum?

Acum, când ceva este schimbat, deoarece vechiul mod nu a funcționat și noul mod este contra-intuitiv, cred că ar trebui să fie comentat în cod, pentru că este necesar să se cunoască pentru totdeauna „Acest lucru nu a funcționat, nu fă-o din nou. ştiu că pare că ar face mai mult sens. Totuși, nu o fac.“ Altfel, eu nu văd că ajută.

Publicat 13/03/2009 la 02:19
sursa de către utilizator

voturi
0

Mergând să aibă o lovitură de cuțit la a răspunde la această mine.

Documentarea fiecare schimbare în sursa face dificil de citit, cu toate acestea, dacă există o piesă deosebit de contraintuitiv de cod acolo și a fost introdus pentru un anumit bilet pus o notă de acesta ca de ce codul este ciudat.

Dar codul ar trebui să fie în continuare documentate. Deci, în timp ce nu face pus în

/* ticket 101: add blink tag to headers, JF - 20010102 */

Este posibil să doriți să pună în

/* make headers blink */

Destul de des, atunci când oamenii nu mai fac primul tip de comentarii, au tăiat masiv pe comentariile lor și acest lucru este rău.

Publicat 16/03/2009 la 15:49
sursa de către utilizator

Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more