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

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ę?

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.

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.

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.

Nie.

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

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).

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.

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.

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.

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 :)

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.

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.

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 .

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ń.

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.

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.

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.