Czy w komentarzach do programu można umieścić link do stron z pytaniami i odpowiedziami?

16

W dość niektórych bazach kodów można zobaczyć komentarze stwierdzające takie rzeczy jak:

 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade)

Mam więc kilka pytań, ale wszystkie są powiązane.

Czy w komentarzach programu można umieścić link do pytań SO:

 // We're now mapping from the "sorted-on column" to original indices.
 //
 // There's apparently no easy way to do this in Java, so we're
 // re-inventing a wheel.
 //
 // (see why here, in SO question: http://stackoverflow.com/questions/951848)

Czy to robisz?

Jakie są wady tego działania? (patrz mój pierwszy komentarz dla strasznej wady)

comments Tristan St.
źródło
9
Komentując sobie: jeden bardzo dotycząca wadę, gdy robi to, że ze względu na fakt, że tak jest Wiki istnieje dokładnie zerowy gwarancja, że odpowiedź (ów), które polegają na nadal będą prawidłowe (lub nawet jeszcze tam być). Do licha, w niektórych przypadkach samo pytanie może zostać zamknięte lub zmienione z pierwotnego znaczenia. Ogromna różnica między „Zobacz błąd 1434594” na paradzie błędów firmy Sun polega na tym, że masz gwarancję, że tekst z linku do błędu firmy Sun nie zmieni się ( „nie będzie”, jak zdefiniowano w RFC2119). To jest ogromne: fakt, że SO jest wiki, denerwuje mnie umieszczaniem linków SO w komentarzach.
Tristan St.
7
Najlepiej jest umieścić jasne i zwięzłe podsumowanie odpowiedzi SO, a następnie umieścić link referencyjny pod tym. Robiłem to już kilka razy. W ten sposób, jeśli SO kiedykolwiek spadnie lub odpowiedź zostanie usunięta / zredagowana, podstawowe informacje, które chciałeś, są nadal w podsumowaniu. Teraz, w zależności od złożoności odpowiedzi, napisanie streszczenia może być zupełnie odrębnym obowiązkiem. Jeśli odpowiedź SO zawiera link do czegoś innego, warto link do tych (szczególnie jeśli są one mniej efemeryczne niż odpowiedzi SO).
FrustratedWithFormsDesigner
5
@Robert S .: nie, to nie jest meta. Tu nie chodzi o SO: akceptuję SO takim, jaki jest. Dotyczy to w szczególności sposobu postępowania z zasobem podobnym do SO z komentarza.
Tristan St.
1
Czy mówisz o kodzie, który piszesz dla swojego zespołu? Poprosić ich.
1
Zawsze możesz zapisać całą stronę jako kompletną stronę internetową, skompresować ją i umieścić w folderze dokumentów.

Odpowiedzi:

7

Zrobiłem to, może nie specjalnie dla Przepełnienia stosu, ale dla blogów technicznych, forów, Usenetu, Grup dyskusyjnych Google lub innych miejsc, w których „dlaczego to zrobiłem” może nie być całkowicie jasne z kontekstu.

Nie rozumiem, dlaczego używanie SO w ten sposób byłoby złe, chyba że archiwizują i usuwają stare pytania (co nie wydaje mi się, że tak, ale nie jestem pewien) - ale nawet jeśli tak, to nie gorsze niż jakakolwiek inna strona.

Jeśli naprawdę się o to martwisz, zawsze możesz zrobić zrzuty ekranu lub pobrać te strony jako tekst (lub przejść przez trud uzyskania zdjęć, arkuszy stylów itp.) I zapisać je w repozytorium wiedzy w firmie, dołączając unikalny identyfikator i umieszczenie tego unikalnego identyfikatora w komentarzach, aby umożliwić późniejsze odwoływanie się do niego - wtedy będziesz mieć spójne miejsce na tego typu rzeczy. Ale może to być przesada, w zależności od złożoności i ważności twojego kodu.

Joe Enos
źródło
5

Ogólnie najlepszym sposobem na utworzenie tego linku jest system kontroli wersji i / lub system śledzenia błędów. Warunkiem tego jest jednak to, że możesz dokładnie połączyć swój kod z modułem śledzenia błędów lub miejscem w systemie kontroli wersji, w którym umieszczasz swoje komentarze.


źródło
to ciekawe: tak naprawdę sugerujesz, że w przypadku odpowiedzi SO mógłbym pobrać HTML i zapisać go w moim DVCS (Mercurial, ale nie o to chodzi)?
Tristan St.
Cóż, zwykle nie potrzebujesz całej rzeczy, tylko odpowiednie bity, prawda? I możesz odwołać się do źródła.
5

Idealnie twój kod nie potrzebuje takich komentarzy, ponieważ jest dobrze skonstruowany itp. Ale tak, kiedy twoja sytuacja jest mniej niż idealna, dopuszczalne jest umieszczanie takich komentarzy. Linki do stackoverflow.com są równie dobre (i często lepsze!) Niż inne.

Mamy nadzieję, że są to komentarze tymczasowe, a będziesz mógł wrócić i poprawić kod i usunąć te komentarze .

Nie umieściłem jeszcze linku StackOverflow.com w moim kodzie. Staram się unikać umieszczania linków w kodzie, ponieważ jest to nieprzyjemny zapach, ale kiedy przyjdzie czas, nie zawaham się.

Edycja : Myślę, że moja powyższa odpowiedź sprawia wrażenie, że takiej uwagi można uniknąć. Oczywiście czasami nie da się tego uniknąć; to błąd w bibliotece lub kiepski projekt API, nad którym nie masz kontroli. Takie komentarze, w tym linki, są bardzo pomocne dla następnego programisty.

Patrick Karcher
źródło
2
hej, spójrz na to, chciałbym , aby był „czystszy” sposób na poradzenie sobie z tym, ale bardzo często nie jest to przypadek stackoverflow.com/questions/951848 Mam na myśli, błędy i niespójności / dziwne API, nieudokumentowane zachowanie itp. są częścią życia naszego programisty :)
Tristan St.
2

Widzę to jak pisanie pracy badawczej. Jeśli korzystam z cudzych pomysłów, muszę je docenić. Użyłem już odpowiedzi z stackoverflow w moim kodzie i dodałem link do komentarzy metody.

Jak ktoś wspomniał, SO jest stylem wiki, więc możliwe, że może się zmienić, ale ogólnie pomysł powinien pozostać taki sam.

Nadal powinieneś doceniać innych, kiedy korzystasz z ich pomysłów.

jmq
źródło
1

Jeśli trzeba zaimplementować obejście i nie jest oczywiste, dlaczego implementacja została wykonana w określony sposób, należy naprawdę dopuścić komentarz, aby określić powody. Wydaje mi się, że umieszczenie linku do referencji online jest w porządku, ale naprawdę powinieneś zwięźle skomentować swój komentarz, ale na tyle kompletny, że link dostarczy tylko wyjaśnienia, jeśli czytelnik poczuje potrzebę ponownego sprawdzenia twojego rozumowania.

Jeśli z drugiej strony kod został skopiowany dosłownie, to link do oryginalnego źródła jest tylko sprawiedliwy i może być wymagany w zależności od brzmienia licencji, na podstawie której pozwolono ci kopiować dzieło autora.

S.Robins
źródło