W poście Najczęściej spotykane błędy w pytaniach na forum opisałem najczęstsze i najbardziej frustrujące problemy z pytaniami na forach. W tym postaram się przekazać kilka rad jak unikać błędów podczas zadawania pytań, co robić aby pytanie było dobre i jak pomóc innym pomóc Tobie.

W skrócie można powiedzieć: wykaż minimum chęci i zainteresowania. Jeśli nie widać, że Tobie zależy na rozwiązaniu problemu, to tym bardziej nie będzie na tym zależało kompletnie obcym ludziom.

Dodatkowo, podobnie jak w metodzie gumowej kaczuszki, często sam akt przygotowywania opisu problemu jest wystarczający, aby znaleźć jego przyczynę i ją zlikwidować.

Nie antagonizuj społeczności

Być może jest to dla niektórych zaskakujące, ale pomocy udzielają wolontariusze. Zniechęcanie ich do pomocy nie jest sensowne, a okazanie im minimum szacunku jest naprawdę proste – wystarczy przestrzegać łatwych reguł danego serwisu. Najczęściej jest to coś w stylu:

• wpisz swoje pytanie do wyszukiwarki i zobacz, czy nie ma na nie już odpowiedzi,
• odpowiednio otaguj swoje posty (zgodnie z regułami, jeśli takie są skodyfikowane),
• dodaj (lub nie) języki/technologie w tytule wątku,
• w razie potrzeby popraw treść pod względem ortografii i składni.

Tytuł

Tytuł posta/zapytania to pierwsze, co większość użytkowników zobaczy. Jeśli będzie deskryptywny to może przypomnieć komuś, kto miał identyczny problem w przeszłości, jak sobie z nim poradził. Dobrym tytułem może być “Usuwanie liścia z drzewa BST” lub “Za długi czas obliczeń zadania PRIME_T na spoju”. Po przeciwnej stronie spektrum są “POMOCY!!!”, “Problem” lub “zadanie”.

Treść posta

Opisz swój problem:

• “Nie działa”, “wywala się” lub “co jest źle” nie są akceptowalnymi opisami,
• zamieść informację co robisz, jak próbujesz ten problem rozwiązać, jakiego wyniku oczekujesz, a jaki otrzymujesz,
• jeśli trzeba przeklikać się przez menu, aby dojść do testowanego kodu (ogółem to powinno być zbędne, patrz niżej na sekcję MCVE), podaj sekwencję wyborów,
• podaj konkretne dane, dla których otrzymujesz niepoprawny wynik,
• zamieść odpowiednie fragmenty kodu, ale staraj się zamieścić tylko te powiązane z problemem (ale jeśli nie wiesz czy dany fragment jest istotny, to lepiej zamieść za dużo, również patrz niżej)
• jeśli zamieszczasz kod:
  • upewnij się, że umieszczasz go w odpowiednich tagach, aby wyświetlić kod z kolorowaniem składni i stałą długością czcionki,
  • sformatuj go. Większość IDE pozwala na sensowne formatowanie kodu, są też formatery on-line, jak na przykład http://format.krzaq.cc.

Następnie, za pomocą funkcji podglądu posta, upewnij się, że wszystko wygląda zgodnie z zamierzeniami. Przede wszystkim sprawdź, czy nie ma w nim błędów w formatowaniu – czy wszystkie tagi oznaczające fragmenty kodu są poprawnie otwarte i zamknięte.

Tagi

Przede wszystkim – dostosuj się do zasad panujących w danym serwisie. Ale z reguły należy w tagach zamieścić technologię/język programowania i co bardziej zaawansowane problemy. O ile while nie będzie dobrym tagiem, to już neural-networks może być. Jeśli dana technologia może być opisana na kilka sposobów, np. C++/cpp/cplusplus dla języka programowania C++, znajdź kanoniczną formę zapisu dla danego serwisu.

Przygotuj dobry przykład problemu – MCVE

(treść bardzo mocno inspirowana opisem ze stacka)
Opisując problem, często zachodzi potrzeba przedstawienia go w postaci kodu. Do tego należy stworzyć odpowiedni przykład. Ta sekcja przedstawia rady jak stworzyć idealny przykład. O ile ideał nie zawsze jest możliwy do uzyskania, to warto do niego dążyć. Ponadto, w tym przypadku jest on osiągalny w znaczącej większości przypadków.

MCVE – Minimal, Complete, and Verifiable example, czyli:

• minimalny – zawierający jak najmniej kodu, ale wciąż prezentujący opisywany problem,
• kompletny – zawierający wszystkie niezbędne elementy do reprodukcji problemu (biblioteki, definicje, stałe itd.),
• weryfikowalny – na pewno reprodukujący ten problem, najlepiej na jakiejś niezależnej platformie,
• przykład.

Minimalny

Im więcej kodu zamieścisz, tym mniej ludziom będzie się go chciało czytać i tym ciężej będzie wyłapać faktyczne błędy. W ramach możliwości zamieść najmniejszy możliwy fragment kodu. Można to zrobić na dwa sposoby:

• Utwórz nowy plik/projekt, przenosząc wyłącznie niezbędne fragmenty. Ta metoda jest szczególnie przydatna, gdy masz podejrzenia gdzie jest problem, a kodu w systemie jest zbyt dużo lub nie możesz go pokazać z różnych względów.
• Dziel i rządź. Jeśli masz mniejszy projekt, ale nie wiesz gdzie jest problem, usuwaj kolejne fragmenty tak długo, aż problem zniknie. Gdy to się stanie, cofnij ostatnią zmianę.

Bardzo często, już podczas minimalizacji przykładu możesz znaleźć źródło problemu.

Warto zauważyć, że przykład ma być minimalny aby zwiększyć czytelność, a nie dla minimalizacji samej w sobie. Dlatego też nie minifikuj kodu, nie zmieniaj deskryptywnych nazw zmiennych, funkcji, klas, modułów itd. na jednoliterowe. No i oczywiście sformatuj kod, ale o tym już pisałem.

Kompletny

Upewnij się, że przykład się kompiluje/interpretuje/wstaw-czasownik (o ile pytanie nie dotyczy problemu z tą właśnie fazą). Jeśli potrzebne są jakieś ustawienia, zewnętrzne zasoby lub podpięte biblioteki czy importy, umieść je. Jeśli w innym pliku zadeklarowałeś jakąś funkcję lub klasę niezbędną do zobrazowania problemu, pokaż ją w przykładzie. W skrócie: niech przykład zawiera wszystkie niezbędne elementy do reprodukcji Twojego problemu.

Weryfikowalny

Upewnij się, że Twój przykład udowadnia istnienie tego konkretnego problemu i żadnego innego. Tak więc jeśli nie dotyczy błędu kompilacji, to niech kompiluje się bez zastrzeżeń. W miarę możliwości, upewnij się, że jest powtarzalny na innym systemie/maszynie. wandbox.org lub podobne strony pomogą w weryfikacji wyników na innej maszynie oraz w podzieleniu się tymi wynikami z innymi.