Dobry pomysł, aby wstawić numery błędów w komentarzu na początku pliku źródłowego? [Zamknięte]

40

Czy dobrą praktyką jest umieszczanie numerów błędów w samym pliku w komentarzu nagłówka?

Komentarze wyglądałyby mniej więcej tak:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Wydaje się to pomocne, ale czy uważa się to za złą praktykę?

Geek
źródło
23
Pytanie, które zadam, brzmi: „Co możesz zrobić z osadzonymi numerami błędów, których nie możesz zrobić w bazie danych błędów?” Nie mogę wymyślić żadnych rzeczywistych przypadków użycia.
M. Dudley,
6
@JensG Dlatego umieściłeś go w komunikacie zatwierdzenia, a a logw pliku da ci dokładnie to samo, ale bez bałaganu w pliku ...
Izkata
1
@JensG A kiedy poprawiłeś wyniki lub setki błędów w określonym pliku? Oczywistą odpowiedzią jest to, że od czasu do czasu
usuwasz
3
To pytanie jest przedmiotem artykułu Ars Technica Czy powinniśmy wymienić błędy w nagłówku pliku źródłowego? (opublikowano 15 dni po opublikowaniu tego pytania).
Peter Mortensen

Odpowiedzi:

107

Widziałem to już wcześniej, zarówno ręcznie przez autorów, jak i automatycznie za pomocą skryptów i wyzwalaczy zintegrowanych z systemami kontroli wersji w celu dodania autora, komentarza i daty do pliku.

Myślę, że obie metody są dość okropne z dwóch głównych powodów. Po pierwsze, dodaje bałaganu i szumu do pliku, zwłaszcza gdy komentarze te się starzeją i stają się nieistotne dla bieżącego stanu pliku. Po drugie, są to duplikaty informacji z tego, co jest już utrzymywane w systemie kontroli wersji, a jeśli używasz nowoczesnego systemu kontroli wersji, który obsługuje zestawy zmian, to w rzeczywistości traci informacje o zmianach.

Jeśli już, rozważ integrację z systemem śledzenia defektów. Niektóre narzędzia pozwalają połączyć numer identyfikacyjny wady lub zadania w komentarzu do odprawy z pozycją w narzędziu do śledzenia. Jeśli masz wszystkie swoje wady, żądania ulepszeń i zadania robocze w narzędziu, możesz w ten sposób zapewnić powiązanie. Oczywiście wiąże się to z wadą zależności od tych narzędzi w projekcie.

Thomas Owens
źródło
2
„a jeśli korzystasz z nowoczesnego systemu kontroli wersji, który obsługuje zestawy zmian, w rzeczywistości traci informacje o zmianach”. - czy możesz opracować, proszę?
Geek
10
@Geek Nie jestem pewien, co wyjaśnić. Jeśli spojrzysz na plik, który odwołuje się do numeru identyfikacyjnego błędu, nie zobaczysz zmian innych plików w wyniku tej samej wady, chyba że przeszukujesz pliki. Taki właśnie jest zestaw zmian - zbiór plików zarejestrowanych razem.
Thomas Owens
9
Dodałbym również, że jeśli przejdziesz do nowego systemu śledzenia błędów, wszystkie te liczby natychmiast stają się bezwartościowe. Natknąłem się na to w mojej obecnej pracy, w której niektóre komentarze mają numery z oprogramowania do śledzenia błędów, które nie było używane od 10 lat.
17 z 26
2
Po przejściu na nowy system śledzenia błędów stają się tak przydatne, jakby ich nigdy nie było. Ale zakładając, że w pewnym momencie dostarczyli pewnej wartości i nie dają żadnej wartości ujemnej, dlaczego by tego nie zrobić?
Cruncher
@ 17of26 - Wyobrażam sobie, że można połączyć stare błędy / problemy z nowymi, jeśli nie będzie to żaden inny mechanizm niż komentarz taki jak „stary błąd śledzenia problemów 1234”.
Kenny Evitt
42

Jest dokładnie jeden przypadek, w którym bym to zrobił, a mianowicie jako ostrzeżenie dla przyszłych programistów: „Nie wywołuj funkcji foo()bezpośrednio tutaj; spowodowało to błąd # 1234, a mianowicie ...”, a następnie krótki opis błąd następuje.

A jeśli kod zmienił się w taki sposób, że nie ma pokusy, aby zadzwonić foo()bezpośrednio, usuń ten komentarz. To tylko drażniłoby i wysadziło kod.

rem
źródło
19
Może jestem trochę trudny, ale jeśli foo()nie należy go wywoływać bezpośrednio, kod powinien być tak skonstruowany, aby nie mógł.
MetaFight,
20
Och, próbowałem napisać coś jako przykład, aby tekst był bardziej konkretny - nie bierz mnie zbyt dosłownie. Lepszym przypadkiem byłby przypadek, w którym użyłeś biblioteki zewnętrznej, a funkcja, której normalnie używałbyś do określonego celu, zawierała błąd. Wtedy komentarz „Nie dzwoń foo()tutaj” byłby rozsądny.
rem
16

Jest to całkowicie okropna praktyka. Dodaje wysiłku, aby osiągnąć efekt, który jest czystym powielaniem; innymi słowy, jedyną rzeczą, którą dodaje poza używaniem dzienników zatwierdzeń, jest możliwość tworzenia niespójności. Twoje pliki źródłowe są zaśmiecone nieograniczoną ilością rzeczy, na które nigdy nie patrzysz.

Jedyną zaletą, jaką mogę w ogóle dostrzec, jest to, że można zrekonstruować historię źródłową bez dostępu do kontroli wersji, np. Podczas studiowania wydruku. Ale bardzo niewiele osób jest wystarczająco kompetentnych, aby śledzić zawiłości związane z tworzeniem oprogramowania, a jednocześnie nie jest w stanie zrozumieć kontroli wersji.

Kilian Foth
źródło
Jak myślisz, ile błędów jest możliwych w jednym pliku, a jeśli jest ich tak wiele, to prawdopodobnie czas na przepisanie.
Andy
11

Nie.

Tak robili ludzie, zanim użyli systemu kontroli wersji (tj. Kiedy kod źródłowy był tylko kopią zapasową w plikach zip).

Neil Barnwell
źródło
2
który był swego rodzaju systemem kontroli wersji (i taki, który widziałem używany operacyjnie w programach komputerowych już w 2006 roku i bez wątpienia jest gdzieś używany).
jwenting
1
@jwenting Widziałem pytania na tej samej stronie od osób, które niefortunnie na tyle pracują w sklepach, w których jest to obecnie praktyka :-(
Carson63000,
Używamy świetnego systemu kontroli źródła. Nikt oprócz mnie nie umieszcza komentarzy podczas sprawdzania kodu. <shrug> Komentuję pewne rzeczy (np. PLSQL, który nie zawsze jest śledzony przez SCM). Komentuję mój kod, aby go wyjaśnić, ale nigdy nie wiążę go z konkretnymi błędami, ale zawsze odwołuję się do błędów w SCM, zatwierdzając komentarze podczas meldowania się. Mam nadzieję, że w końcu ktoś to doceni.
Pedantyczny
11

To jest, IMHO, bardzo zły pomysł. Po numerze wersji 100 będziesz mieć 90% komentarzy i 10% kodu. Nie uważałbym tego za czyste i czytelne.

Widzę tylko, że musisz wymieniać kod między SCC i, z jakiegokolwiek powodu, nie możesz przenieść historii między dwoma systemami (ale nawet jeśli w ten sposób zapiszesz komentarze historii, utracisz historię różnic) również zapisywanie komentarzy tylko trochę pomoże).

Doktor Brown
źródło
8

Widzę, że wszyscy są przeciwni temu pomysłowi i podali historyczny powód (era przed kontrolą źródła), dlaczego ludzie to robią.

Jednak w mojej obecnej firmie programiści baz danych przestrzegają tej praktyki i dodatkowo oznaczają numer błędu wokół fragmentu kodu. Czasami uważam to za pomocne, gdy widzisz błąd w kodzie i możesz od razu znaleźć poprawkę, która wprowadziła ten problem. Jeśli nie mamy tych informacji w moim pakiecie bazy danych, z pewnością nie będzie łatwo znaleźć główną przyczynę tej implementacji.

Tak, zaśmieca kod, ale pomaga znaleźć powód, dla którego ten fragment kodu istnieje.

Parvez
źródło
3
Absolutnie. Czasami mam wrażenie, że programiści są przerażeni redundancją, dlatego unikają dostępu do tych samych informacji na różne sposoby. To bardzo interesujące, ponieważ programiści są zwykle przerażeni niską wydajnością i dlatego używają pamięci podręcznych w swoich programach. Ale buforowanie numerów błędów w kodzie obok miejsca, w którym są najbardziej przydatne, jest uważane za złe? Mmm
JensG
Często jest inny sposób na uzyskanie tych informacji (w projekcie, nad którym pracuję, byłoby right click > Team > Show Annotationsobwinienie bieżącego pliku), ale różnica polega na tym, że w przypadku komentarzy istnieje możliwość wykrycia - mogą wyskoczyć na ciebie - a wraz z adnotacjami musisz świadomie zdecydować, aby ich poszukać.
David Conrad
Myśl, decyduj, kliknij, kliknij, kliknij, przewiń. Dlatego powiedziałem „buforowanie w kodzie”. Jeśli tam jest, po prostu to widzę.
JensG
2
@JensG Interesujący punkt widzenia. Skrytki mogą poprawić wydajność, ale wiążą się również z kosztami przenoszenia. Gdyby pamięć podręczna musiała zostać wypełniona, zaktualizowana, unieważniona, opróżniona itd. Zbędnym wysiłkiem człowieka, zakwestionowałbym stosunek kosztów do korzyści, szczególnie biorąc pod uwagę, jak okropni ludzie utrzymują synchronizację takich zdenormalizowanych konstrukcji.
Jeffrey Hantin
7

Jednym z punktów testu Joela jest

Czy masz bazę danych błędów?

Takie informacje mogą być przechowywane w bazie danych błędów, jeśli uważasz, że są ważne, ale w komentarzach byłyby tylko szumem.

Pierre Arlaud
źródło
1
Zobacz przykład w pytaniu - komentarze odnoszą się do bazy danych błędów ...
Izkata
@Izkata Ale o to chodzi. Sama baza danych może mieć pole „komentarz” z komentarzem. Pytanie nie dotyczy posiadania bazy danych błędów, ale nie to, czy dobrym pomysłem jest utrzymanie tego w pliku źródłowym. Myślę, że nawet jeśli są to komentarze, powinny być przechowywane w samej bazie danych, ponieważ po to jest.
Pierre Arlaud,
6

Myślę, że masz tutaj dwa problemy. Po pierwsze, dlaczego powinieneś polegać wyłącznie na różnicach, skoro większość systemów pozwala na wprowadzanie komentarzy do wersji? Podobnie jak dobre komentarze do kodu, odkrywasz, dlaczego dokonano zmiany, a nie tylko samą zmianę.

Po drugie, jeśli masz taką możliwość, umieść je wszystkie w tym samym miejscu. Nie ma potrzeby przeglądania pliku pod kątem zaznaczonych linii kodu, które nie są już potrzebne. Komentarze wewnątrz działającego kodu mają na celu wyjaśnienie, dlaczego jest on kodowany w ten sposób.

Po wprowadzeniu tego w życie utworzone nawyki ułatwiają wszystkim pracę z bazą kodu.

Powiązane śledzenie błędów i funkcji oraz dlaczego zmieniasz ten plik, może dać ci wyobrażenie o tym, jak głęboko musisz zagłębić się w historię i być może spojrzeć na różnice. Miałem prośbę o „Powrót do oryginalnej formuły”. Wiedziałem dokładnie, gdzie się udać w historii zmian i sprawdziłem tylko jedną lub dwie różnice.

Osobiście zaznaczony kod wygląda jak praca w toku dla problemu, który jest rozwiązywany metodą prób i błędów. Usuń ten bałagan z kodu produkcyjnego. Możliwość łatwego wsuwania i wyjmowania wierszy kodu ułatwia jedynie pomylenie.

JeffO
źródło
2

Jeśli nie masz VCS z komunikatami zatwierdzania i nie masz systemu śledzenia błędów z opcją dodawania komentarzy, jest to jedna, a nie optymalna opcja, aby śledzić zmiany.
Lepiej mieć arkusz kalkulacyjny z tymi informacjami lub, jeśli jesteś w środowisku bez takich „luksusów”, plik tekstowy siedzący gdzieś w pobliżu źródeł.
Ale zdecydowanie polecam, jeśli jesteś w takim środowisku, aby zacząć budować argumenty przemawiające za zainwestowaniem w VCS i system śledzenia błędów :)

jwenting
źródło
2

Pamiętaj o tym - kod jest często dłuższy niż narzędzia, które go obsługują. Innymi słowy, moduły do ​​śledzenia problemów, kontroli wersji i wszystkie inne skrypty będą ewoluować w trakcie rozwoju. Informacje gubią się.

Chociaż się zgadzam, bałagan w plikach jest denerwujący, otwieranie pliku i rozumienie jego historii bez uciekania się do korzystania z narzędzi, zawsze było bardzo pomocne - szczególnie jeśli utrzymuję kod.

Osobiście uważam, że jest miejsce zarówno na narzędzia, jak i dziennik w kodzie.

ggb
źródło
2

Wiem, że Git tego nie robi, a prosta odpowiedź brzmi „dlaczego, do licha, miałaby się tam udać?”

Ogólnie jest to mniej modułowa konstrukcja. W ramach tego rozwiązania teraz pliki stanowią mieszankę treści i metadanych. Amazon S3 to kolejny przykład usługi do przechowywania plików, które nie dodają frontu YAML ani tym podobnych do plików.

Każdy konsument pliku jest zobowiązany do przetworzenia go najpierw przez system kontroli wersji. To jest ścisłe sprzężenie, np. Twoje ulubione IDE pęknie, jeśli nie obsługuje twojego VCS.

djechlin
źródło
2

Nie, śledzenie poprawek błędów jako komentarzy w kodzie nie jest dobrą praktyką. To tylko generuje bałagan.

To samo powiem o wiadomości o prawach autorskich, o której wspomniałeś. Jeśli nikt poza Twoją firmą nigdy nie zobaczy tego kodu, nie ma powodu, aby podawać informację o prawach autorskich.

Jeśli używasz oprogramowania do śledzenia wersji ( Git , SVN itp.), Powinieneś dołączyć te uwagi do wiadomości zatwierdzania. Nikt nie chce przekopywać nagłówków każdego pliku kodu, aby wygenerować informacje o wersji lub zobaczyć przegląd wprowadzonych zmian. Te dzienniki zmian powinny być przechowywane razem, w historii śledzenia wersji, w narzędziu do śledzenia defektów lub w obu tych przypadkach.

Jeśli szukasz dobrej lektury na ten temat, polecam czwarty rozdział Clean Code .

Brian
źródło
Informacje o prawach autorskich mają również (nieco nadmiarowo) informować pracowników, że plik należy do pracodawcy. A może zniechęca nielegalnego udostępniania (nawet pracowników), sądząc po ilu ludziom wydaje się, że prawo autorskie ma zastosowanie tylko wtedy, gdy jest zawiadomienie.
Bernd Jendrissek
1

Myślę, że są inne elementy tej dyskusji, o których często się zapomina, ale są przypadki, w których komentarz do wersji jest szybki dla zespołu.

Podczas pracy w środowisku zespołu ze współużytkowaną bazą kodu i gdy kilku członków zespołu potencjalnie pracuje w tych samych obszarach kodu, umieszczenie krótkiego komentarza do wersji w odpowiednim zakresie (metoda lub klasa) wskazującego, że dokonano zmiany, może być bardzo przydatne dla szybkie rozwiązywanie konfliktów scalania lub meldowania.

Podobnie podczas pracy w środowisku, w którym zaangażowanych jest kilka (funkcjonalnych) gałęzi, trzeciej osobie (kompilatorowi) łatwiej jest określić, co zrobić, aby rozwiązać potencjalne konflikty.

Za każdym razem, gdy musisz uciec od IDE i zapytać kogoś, dlaczego coś zmienił, ma to negatywny wpływ na wydajność obu członków zespołu. Szybka notatka we właściwym zakresie może pomóc w zmniejszeniu lub wyeliminowaniu większości tych zakłóceń.

StingyJack
źródło
3
pytanie dotyczy komentarza na początku pliku źródłowego, zaraz po wiadomości o prawach autorskich - nie ma to nic wspólnego z komentarzami w węższych zakresach
gnat
Wszystkie odpowiedzi tutaj mówią tylko o tym. Jeśli dokonam znaczących zmian w całym pliku klasy (reorg lub formatowanie), czy nie skomentuję pliku klasy jako zakresu?
StingyJack
0

Wszelkie informacje o błędach bezpośrednio związane z fragmentem kodu stają się nieistotne, gdy integralność całej zmiany jest modyfikowana przez kolejną poprawkę.

Kiedyś dodawanie informacji do podsumowania funkcji było powszechne, gdy musieliśmy polegać na zewnętrznych narzędziach (powiedzmy javadocs), aby tworzyć informacje o wydaniu z kodu. Jest to w większości bezużyteczne lub zbędne dzięki nowoczesnym narzędziom kontroli wersji.

Może to mieć sens tylko jako komentarz w bardzo modularnym fragmencie kodu, jeśli trzeba uciekać się do jakiegoś niejasnego lub nie-gwiezdnego kodowania, które przyszli programiści mieliby ochotę zmienić - nie zdając sobie sprawy z przyczyny - jak w przypadku obejścia błąd biblioteki / wada.

Fiammetta Castaldi
źródło
0

Na pewno nie umieszczałbym takich informacji na początku pliku - zwykle coś takiego należy do systemu zgłoszeń.

Istnieją jednak niektóre przypadki, w których sensowne są odniesienia do systemu biletów i / lub innej dokumentacji. Na przykład, jeśli istnieje długie wyjaśnienie projektu lub opis alternatyw. Lub informacje, jak testować rzeczy, lub wyjaśnienia, dlaczego zrobiono to dokładnie w ten sposób. Jeśli jest krótki, należy do samego pliku; jeśli jest długi i / lub dotyczy większego obrazu, prawdopodobnie będziesz chciał go umieścić gdzieś indziej i odwołać się do niego.

hstoerr
źródło
wydaje się, że nie wnosi to znaczącej wartości do tego, co zostało już opublikowane w poprzednich odpowiedziach
komara
0

Projekt, do którego jestem obecnie przypisany w pracy, miał tego rodzaju listę numerów błędów na początku każdego pliku; jednak żaden z deweloperów wciąż biorących udział w projekcie już się do niego nie dołącza. Większość z nich uważa, że ​​jest to bezużyteczne marnowanie miejsca, ponieważ jest znacznie gorsze od śledzenia błędów w plikach za pomocą naszego systemu kontroli wersji.

W niektórych krytycznych plikach, które przeszły wiele poprawek i ulepszeń, listy te stały się tak duże, że trzeba je przewinąć, aby przejść do kodu. Podczas grepingu te listy mogą powodować kilka fałszywych trafień, ponieważ każdy z nich zawiera krótki tytuł błędu lub krótki opis.

Krótko mówiąc, listy te są w najlepszym wypadku bezużyteczne, aw najgorszym - ogromne, chaotyczne marnowanie miejsca, które utrudnia wyszukiwanie i lokalizowanie kodu.

Fred Thomsen
źródło