Dlaczego cytowanie identyfikatorów błędów w informacjach o łatce może być uważane za złą praktykę?

28

W oparciu o komentarz i kolejne opinie z Bug ponownie otwarte vs. nowe :

Powoływanie się na identyfikatory błędów w opisach poprawek jest po prostu… bardzo nieprzyjazne. - Krelp

Wydaje się, że przynajmniej niektórzy uważają, że odwoływanie się do identyfikatorów błędów w informacjach o łatach nie jest dobrym pomysłem. Jestem dość niedoświadczonym programistą, więc zastanawiam się, dlaczego tak jest.

Travis Northcutt
źródło
27
brak cytowania identyfikatorów błędów w informacjach o łatach jest po prostu ... bardzo nieprofesjonalny. Trochę marnuje cały sens posiadania trackera problemów
gnat
Ten sam powód, dla którego publikowanie tylko linków jako odpowiedzi StackExchange jest niezadowalające - jeśli opublikujesz tylko link, w SE jest to złe, ponieważ (1) wymaga zastosowania się do uzyskania wyjaśnienia i (2) może stać się nieważny w przyszłości, jeśli link umiera lub zawartość się zmienia. Podobnie, umieszczanie tylko identyfikatorów błędów w uwagach do łaty (1) wymaga udania się do narzędzia do śledzenia błędów w celu uzyskania wyjaśnienia, a (2) może stać się nieważny w przyszłości, jeśli zmieni się system śledzenia błędów. Umieszczanie linku w odpowiedzi SE lub identyfikatora błędu w łatce jest w porządku (i właściwie dobrą praktyką) jako dodatek do zwykłego wyjaśnienia.
Ben Lee,

Odpowiedzi:

51

Moim zdaniem jest to dobra praktyka, zakładając, że użytkownicy mają dostęp do odczytu bazy danych błędów. Wiele razy ludzie czekają na naprawienie określonego błędu, aby zdecydować, kiedy dokonać aktualizacji.

Myślę, że to, co się marszczy, to tylko cytowanie identyfikatora błędu i nic więcej. Zawsze powinieneś również podać opis, który jest zrozumiały, bez wchodzenia do narzędzia do śledzenia błędów. Pozwala to również na przełączanie śledzenia błędów w przyszłości bez całkowitego unieważnienia poprzednich informacji o wersji.

Karl Bielefeldt
źródło
Możesz cytować za pomocą abstrakcyjnego resolvera odniesienia, czyli przekierowania adresu URL.
Donal Fellows
Jak mówisz, sekcja „Naprawione błędy” (lub podobna) powinna zawierać identyfikator i tytuł, aby czytelnik nie musiał szukać błędu, aby dokładnie zrozumieć, co jest zawarte, a co nie.
StuperUser
5
@StuperUser - co najmniej identyfikator i tytuł .
Oded
To, co denerwuje, to znajdowanie w komentarzach tylko informacji o błędach, gdy wspomniany system identyfikatora błędu / wymagania nie jest już używany.
jfrankcarr
14

Jest, jak powiedziano w cytowanym komentarzu ... nieprzyjazny.

Nieprzyjazny sobie

Wyobraź sobie następujący scenariusz. Oglądasz dzienniki w kontroli źródła. Zastanawiasz się, co zmieniło się zatwierdzenie. Zamiast objaśniać to zwykłym angielskim, mówi ci:

Rozwiązane # 1307

Prowadzisz system śledzenia błędów, mając nadzieję, że znajdziesz coś pomocnego. Błąd nr 1307 jest zgłaszany jako rozwiązany. W opisie widać:

Ten sam błąd, co # 1284

Dzięki, to bardzo pomocne. Musisz teraz przejść do raportu o błędzie # 1284, aby przeczytać, że jest to duplikat błędu # 1113, który odnosi się do błędów # 1112, # 1065 i # 1067.

Pięć minut później nie masz pojęcia, czego szukasz na początku.

O wiele bardziej przydatnym komunikatem dziennika kontroli wersji byłoby:

Rozwiązano problem polegający na tym, że użytkownicy nie mogli zalogować się przy użyciu hasła dłuższego niż 25 znaków (patrz nr 1307), usuwając stosowanie tej samej zasady długości hasła do warstwy dostępu do danych, jak ta używana w samej witrynie.

W ten sam sposób, w systemie śledzenia błędów, raport nr 1307 może być bardziej zrozumiały , przypominając o czym był raport o błędzie # 1284 i jak nowy różni się od starego.

Nieprzyjazny dla klientów

To nie jedyny problem życzliwości.

Po drugie, odwołując się do zbyt dużej liczby bez dodatkowych informacji, sprawiasz, że notatki o łatce / dzienniki kontroli wersji / raporty systemu śledzenia błędów są bezużyteczne dla osób niezbyt dobrze zaznajomionych z tymi systemami . Kiedy codziennie zajmujesz się systemem śledzenia błędów, wiesz, jak szybko poruszać się po raportach, przeglądać wiele raportów obok siebie itp. Gdy jesteś klientem bez zaplecza technicznego, łatwo możesz się zgubić.

Ponownie, bardziej szczegółowe wiadomości są bardzo pomocne niż tylko odniesienie. Pamiętaj, że nadal chcesz zachować referencje: nic nie jest bardziej złe niż błąd, który jest taki sam jak błąd napotkany dwa tygodnie temu, ale nie pamiętaj jego identyfikatora.


Należy zauważyć, że ten sam problem występuje w wielu jurysdykcjach. Na przykład we Francji ustawodawstwo odwołuje się do wielu źródeł, które mogą się w międzyczasie zmienić. Oznacza to, że aby go w pełni zrozumieć, trzeba czasem spędzać godziny w bibliotece, szukając dziesiątek tekstów odsyłających, z których każdy ma własne odniesienia do innych.

Arseni Mourzenko
źródło
5
To nie jest problem z dokumentem wydania; jest to problem z poziomem szczegółowości błędów. Tytuł powinien opisywać rzeczywisty problem, a treść każdego błędu powinna zawierać oczekiwany wynik i rzeczywisty wynik. Czy błędy, które opisałeś, nie powinny być zamykane jako duplikaty?
StuperUser
Na podstawie Twojej edycji. Cytujesz identyfikator w znacznie bardziej pomocnej wiadomości. Czy miałeś na myśli w swoim oryginalnym komentarzu, że cytowanie TYLKO Ids bez dalszych informacji jest nieprzydatne, podczas gdy prawidłowe wyjaśnienie ORAZ identyfikator jest pomocne?
StuperUser
1
@StuperUser: dokładnie. Dostarczenie wyjaśnień pomaga osobom, które chcą tylko wiedzieć, o czym jest dziennik zatwierdzenia / informacja o łatce / raport o błędzie, bez poświęcania dziesięciu minut na czytanie odnośnej zawartości. Identyfikatory są nadal wymagane do śledzenia, a osoby, które potrzebują bardzo szczegółowych, precyzyjnych i pełnych informacji.
Arseni Mourzenko
2

Nie ma nic złego w cytowaniu numerów problemów w notatkach o poprawkach, pod warunkiem, że użytkownicy mogą przeczytać cytowany problem. Jeśli baza danych błędów pozwala komukolwiek czytać, cytowanie numeru błędu może być bardzo przydatne. (Jeszcze lepiej, jeśli notatki łatek są w formacie, który pozwala na linki, spraw, aby te identyfikatory problemów były linkami do danego problemu.) Nie oznacza to, że powinieneś ujawnić wszystkie problemy ogółowi; nadal przydatne mogą być takie, które są owiane (np. tam, gdzie mają aktywne hasła!)

Powoływanie się na numer problemu, w którym osoba czytająca nie może przejść i sprawdzić szczegółów i historii błędu, jest dość nieprzyjazne. Nie że cytowanie takich problemów bez identyfikatora problemu jest o wiele bardziej przyjazne.

Donal Fellows
źródło
„tam, gdzie osoba czytająca nie może iść i sprawdzić szczegółów”, jako taka osoba , nie nazwałbym tego naprawdę nieprzyjaznym. Użyłem identyfikatora problemu do komunikacji z zespołem wsparcia / deweloperów, który z kolei miał dostęp do narzędzia do śledzenia problemów. To, że był dla mnie osobiście niewidoczny, było jedynie drobną uciążliwością
komara
2

Oczywiście zależy od tego, kim są ludzie, którzy będą czytać informacje o poprawce, oraz od docelowych użytkowników oprogramowania.

Ale w większości przypadków zdecydowana większość użytkowników po prostu nie dba o identyfikator błędu. Nie obchodzi ich, dlaczego została zepsuta, jaka jest poprawka ani nic innego - chcą tylko wiedzieć, co się zmieniło za pomocą bardzo zwięzłego opisu tekstowego, bez konieczności przechodzenia do kolejnej strony z każdą zmianą.

Cytowanie identyfikatorów błędów powoduje, że przestaję myśleć i ja, jako użytkownik, nie chcę myśleć. To rodzaj problemu z użytecznością.

Spójrz na przykład na dzienniku zmian Visual Assist X . Wszystkie powiązane identyfikatory błędów to po prostu hałas, który odciąga mnie od zrozumienia, co się zmieniło. Jest to dodatek do programu Visual Studio, przeznaczony dla programistów. A ja jestem programistą. Jeśli mi to przeszkadza, wyobraź sobie przeciętnego użytkownika, który nawet nie wie, co to jest narzędzie do śledzenia błędów.

PS: Byłem autorem komentarza, który wywołał pytanie

Thomas Bonini
źródło
1
Szczerze uważam, że dokumentacja na końcu tego linku jest pomocna. Zaczyna się od podsumowania, a następnie kieruje mnie do szczegółów. Microsoft często robi podobne linki w artykułach KB, nie dlatego, że to czyni dobrą praktykę, ale z pewnością jest szeroko rozpowszechniony i najwyraźniej zapewnia wartość wielu użytkownikom.
Joshua Drake
1

Identyfikator błędu jest obowiązkowy dla punktu odniesienia . Powody:

  • Zapobiegaj dwuznaczności: dwa lub więcej błędów może mieć podobne opisy. Aby rozróżnić między nimi, potrzebna byłaby kotwica.
  • Wygoda : podczas omawiania błędu, z klientem lub wewnętrznie, identyfikator błędu jest często używany jako krótki formularz. Jeśli identyfikator zostanie pominięty w uwagach do łaty, trudno będzie o nich dyskutować:

3052 został już naprawiony, nadal działa na 3077

jest wygodniejszy niż:

Naprawiono „awarię aplikacji przy przycisku Zastosuj”, która nadal działała w „Wyjątku NullReferenceException po kliknięciu przycisku Zmień użytkownika”

KMoraz
źródło
(1) Co uniemożliwia ci połączenie, jak sugeruje MainMa? (2) Dlaczego popełniasz półtora naprawionego błędu? Dlaczego nie popełniasz błędów po 3052, zanim jeszcze zaczniesz pracować nad 3077?
JensG
0

Powiedziałbym, że to zależy od twojego systemu: mam szczęście, że ten, którego używam, automatycznie wykrywa takie odniesienia w komunikatach zatwierdzania i dodaje link do biletu zapisanego w narzędziu do śledzenia błędów, więc nie jest to problem.

Ale gdybym był w systemie, w którym nie jest dostępny, nadal wspomniałbym o identyfikatorze biletu (w ten sposób można szybko przeszukiwać dzienniki według identyfikatora biletu ) wraz z krótkim opisem tego, co jest błędem.

dzikie piki
źródło