Jak NIE pisać tutoriali

Do napisania tego posta skłonił mnie jeden z tutoriali, z którego miałem okazję niedawno korzystać. Umyślnie nie będę podawał adresu strony, na której on się znajduje ponieważ nie chcę nikomu robić antyreklamy, nie to jest moim celem. Poza tym to co tutaj opisuję nie dotyczy tylko tej jednej strony, ale jest obecne w mniejszym lub większym stopniu w wielu innych miejscach Internetu.

W tym wpisie nie będę poruszał problemu niskiego poziomu merytorycznego niektórych informacji udostępnianych w sieci, bo ten problem nie dotyczy akurat przytaczanego tutoriala i nie on zwrócił moją uwagę. W tym poście poruszę problem skrótów myślowych, niedopowiedzeń i nieścisłości na jakie trafiłem, i które są bardzo irytujące kiedy próbuje się korzystać z wiedzy jaką chciał nam przekazać autor.Szukając w Internecie informacji na temat autoryzacji w ASP.NET MVC trafiłem na stronę, gdzie znajdowały się interesujące mnie informacje. Jednak były one częścią sześcioczęściowego tutoriala poświęconego podstawom ASP.NET MVC 4. Ponieważ dopiero zaczynam przygodę z tą technologią uznałem, że przerobię cały kurs. No i wtedy zaczęły się schody.

Jak pisze autor o tym kursie we wprowadzeniu „[…]set of posts that should cover, at least in the beginning, the most basic aspects about programming in asp.net MVC 4.” Tak więc można zakładać, że opis jest skierowany do osób, które jeszcze niewiele, albo nawet nic nie wiedzą o tej technologii.

Faktycznie, pierwsza część rozpoczyna się od opisu czym jest MVC, potem jest opis metod HTTP, następnie dochodzimy do tworzenia nowego projektu w Visual Studio. Jest opis najprostszej aplikacji webowej. Do tej pory wszystko jest ok, opis jest dokładny, taki jak tego oczekuję jako osoba początkująca. Ale już kawałek dalej, kiedy opisane jest tworzenie pierwszego formularza następuje pierwsza nieścisłość i niejasność. Autor podaje skrypt tworzący 2 tabele w bazie danych. Jedna z tabel ma nazwę Messages (zwracam uwagę na liczbę mnogą), później pisze, że korzystając z Entity Framework tworzymy na podstawie bazy danych jej model w kodzie. Tylko, że w żaden sposób nie rozwija tego zagadnienia, od razu pokazuje gotowe pliki utworzone przez Entity Framework. W tym miejscu musiałem spędzić dłuższą chwilę, alby zmusić do współpracy ten ORM i bazę MS SQL Express. Ale załóżmy, że wpis nie dotyczył EF więc to ostatecznie można wybaczyć (chociaż jest to praktycznie nieodłączna część ASP.NET MVC…). Po przejściu przez ten proces EF utworzył na podstawie tabel m.in. klasę Messages (ponownie zwracam uwagę na liczbę mnogą) odpowiadającą tabeli o tej samej nazwie. Teraz tutorial pokazuje tworzenie widoku dla formularza i tutaj na screenie widzę, że wykorzystana jest klasa Message (tak, tutaj jest liczba pojedyncza). Na początku pomyślałem, że to literówka, ale taka nazwa pojawia się wszędzie dalej.

Dalej, tabela Messages posiada kolumnę Message, i EF wygenerował model z takim właśnie polem. Ale, ale, teraz w przypadku tego pola autor uparcie używa nazwy Message1 (swoją drogą dodawanie liczby do nazwy zmiennej/kolumny jest co najmniej słabym pomysłem). Niby można się domyślić, że jest tutaj rozbieżność i niektórzy po prostu zmieniliby nazwę kolumny w bazie, tylko że… Jeśli ktoś jednak trzyma się nazw użytych w tabelach natrafi na kolejny problem. Mianowicie ten fragment kodu spowoduje błąd w trakcie działania aplikacji:

[HttpPost]
public ActionResult ContactUs(Code.DataAccess.Message message)
{
    return View(message);
}

Pomijam tutaj ponowne użycie klasy Message, która tak na prawdę nie istnieje. Problemem jest nazwa parametru message. Ten fragment sprawił, że ponownie musiałem spędzić dłuższą chwilę z Google. Otóż tutaj chcemy przekazać całą klasę wiadomości, ale klasa Messages ma pole o nazwie message i tutaj pojawia się konflikt. Bo ASP.NET próbuje przekazać w parametrze wartość tego pola odczytaną z formularza, a nie cały obiekt klasy, ponieważ dopasowuje on nazwę znajdującą się w akcji kontrolera do nazwy użytej w kodzie HTML. W konsekwencji parametr ma wartość null i powoduje powstanie błędu.

Kolejna rzecz to polecenie utworzenia jakiejś klasy, ale nie powiedzenie, w którym folderze. A w przypadku platformy ASP.NET MVC umiejscowienie pliku w odpowiednim folderze jest sprawą kluczową. O ile jeszcze w przypadku kiedy autor podaje kod razem z namespace można dojść do tego gdzie taki plik utworzyć to zdarzają się też klasy, które wymagają ściągnięcia paczki zawierającej cały tworzony w tutorialu projekt i popatrzenia gdzie taki kod został wstawiony. Z tą koniecznością pobrania paczki z kodem wiąże się jeszcze jedna, ostatnia rzecz, jaka była bardzo uciążliwa. Mianowicie odwoływanie się do klas, które autor pisał sam, ale poza miejscem ich użycia nigdzie o nich nie wspomniał w tekście. Dla przykładu takie fragment:

DateTime.Now.AddSeconds(WebConfigSettings.CachingTime)

Użyta jest tutaj klasa WebConfigSettings, jednak nigdzie w tekście nie było o niej wzmianki. Więc początkowo założyłem, że jest to może jakaś klasa dostarczana z .NET, ale Visual nie podpowiedział, że powinienem dodać dodatkową dyrektywę using, szukanie w Google też nie dało odpowiedzi. Więc postanowiłem spojrzeć ponownie do paczki z projektem danej przez autora i… w folderze, w którym znajdował się plik z klasą zawierającą powyższy fragment kodu znalazłem również inny plik zawierający szukaną klasę WebConfigSettings. Miała ona tylko jedną funkcję, a właściwie właściwość zwracającą właśnie CachingTime. Wystarczyło napisać jedno zdanie, że taki plik istnieje, nie wspominając już o wklejeniu do posta jego treści, bo to już by był szczyt luksusu.

Cały ten post powstał na podstawie jedynie pierwszej części wspomnianego tutoriala. W kolejnych przedstawione błędy pojawiają się w mniejszej lub większej formie i tak samo irytują i niepotrzebnie wydłużają proste rzeczy.

Tak jak wspomniałem na początku nie poruszałem tutaj kwestii merytorycznej tutoriali znajdujących się w Internecie. Tutaj było raczej w porządku, chociaż momentami widziałem, że autor robił niektóre rzeczy naokoło nie wykorzystując tego co oferuje platforma. A ze wstępu wynika, że osoba to pisząca zawodowo pracuje w tej technologii tak więc tym bardziej można by oczekiwać bardziej profesjonalnego podejścia do tworzonej treści.

Wszystko co tutaj opisałem nie dotyczy jedynie tej jednej strony. Dlatego też w żadnym miejscu nie podałem adresu ani nazwy. Jeśli ktoś przynajmniej od czasu do czasu przerabia tutoriale znalezione w sieci to na pewno znajdzie w nich opisane tutaj irytujące elementy.

Nie twierdzę, że sam umiałbym napisać lepszy poradnik i oczywiście to co autor napisał było dla mnie przydatne i pozwoliło zdobyć nową wiedzę, jednak jeśli chcemy aby Internet był również źródłem w miarę rzetelnej wiedzy to warto zwracać uwagę na takie elementy, tak aby osoby, które na prawdę są początkujące w jakimś zagadnieniu i szukają informacji pozwalających im poznać nowy obszar wiedzy nie zniechęciły już na początku nie mogąc znaleźć rozwiązania pojawiających się niespodziewanie problemów.