Być czy nie być, pisać czy nie pisać komentarze?

Home

Programiści dzielą się na:

• Tych, którzy piszą bardzo dużo komentarzy, czasami prawie w każdej linijce. Tych spotkałem niewielu.
• Tych, którzy w ogóle ich nie piszą, nawet jeśli napisali kod, którego nie da się zrozumieć bez choćby odrobiny komentarza. Tych ortodoksów jest już więcej.
• Największa grupę stanowią natomiast programiści, którzy sytuują się gdzieś pomiędzy tymi dwiema skrajnościami.

Kiedy zaczynałem programować pisałem bardzo dużo komentarzy. Wiele z nich było zupełnie niepotrzebnych, na przykład komentarz "Konstruktor domyślny" dla domyślnego, bezparametrowego konstruktora. Z biegiem lat, kiedy nabrałem doświadczenia przesunąłem się gdzieś w okolicę środka na skali pomiędzy ortodoksyjnymi zwolennikami komentarzy i ortodoksyjnymi przeciwnikami komentarzy. Wciąż bliżej mi jednak do tych pierwszych.

Jednak, ostatnio dwa zdarzenia spowodowały, że częściowo przewartościowałem swój sposób patrzenia na tę sprawę i moje nastawienie przesunęło się znacząco w kierunki nie pisania komentarzy. Co to za zdarzenia? Po pierwsze postanowiłem wrócić do swojego starego projektu napisanego w C# ponad 3 lata temu. W skrócie program realizuje wnioskowanie wstecz. Właściwy silnik wnioskujący ma około 800 linii kodu (nie licząc GUI i definicji prostych struktur danych). Przy czym ponad połowa z tego przypada na komentarze, definicje regionów i znaki nowe linii! Problem w tym, że pomimo dużej liczby komentarzy miałem dużą trudność w zrozumieniu tego kodu i niektórych rozwiązań jakie przyjąłem. Drugie zdarzenie dotyczyło cudzego kodu, w którym skomentowana była prawie każda linijka. Początkowo myślałem, że ułatwi to sprawę ale myliłem się. Tak duża liczba komentarzy skutecznie utrudniała zrozumienie kodu. Usunięcie znaczącej części tych komentarzy (i refactoring) sprawiło, że kod stał się dużo łatwiejszy w odbiorze.

W obecnej chwili uważam, że większe znaczenie ma odpowiedni podział kodu na klasy, a przede wszystkim na metody. Zamiast komentarza lepiej zamknąć kod, którego dotyczy w metodę o samo tłumaczącej się nazwie. Komentarze w kodzie staram się ograniczyć do miejsc, które rzeczywiście tego wymagają: skomplikowany algorytm, szybko wprowadzane poprawki itd. Jeśli chodzi o komentarze do metod to uważam, że są one niezbędne tam gdzie z nazwy metody i nazw jej parametrów nie można wywnioskować jej przeznaczenia. Jeśli mamy skłonność to niepisania komentarzy to warto spytać innego programisty co jego zdaniem robi dana metoda. Jeśli odpowie poprawnie to komentarz z dużym prawdopodobieństwem nie jest potrzebny. Komentarz jest również potrzebny jeśli metoda rzuca jakieś wyjątki. Co jednak z metodami publicznymi i chronionymi czyli tymi, z których potencjalnie będą korzystać inni. Tutaj mam mieszane uczucia. Z jednej strony dobra praktyka mówi, że dla tych metod komentarze są potrzebne. Z drugiej po co komentować metodę o takim nagłowku IList<User> GetAllUsersWithBankAccount(), która zwraca listę użytkowników z kontem bankowym?

Czy to na pewno takie proste?

Home

Czy można zrobić coś źle dodając nowy plik do projektu aplikacji WWW w Visual Studio? Dla ustalenia uwagi niech będzie do plik z definicją raportu wczytywanego w czasie działania tejże aplikacji. Plik ten chcemy w razie potrzeby zmodyfikować bez konieczności ponownej kompilacji projektu. Sprawa wydaje się prosta (Add -> Existing item... itd.) ale jest pewien haczyk. Otóż, Visual Studio dla plików z nieznanymi rozszerzeniami ustawia ich właściwość Build Action na wartość None. Jeśli uruchomimy aplikację z poziomu Visual Studio to nie zauważymy żadnych błędów. Problemy pojawi się jeśli zainstalujemy aplikację na serwerze IIS przy pomocy narzędzia Publish....

Narzędzie to udostępnia kilka sposobów kopiowania plików, a domyślnie zaznaczona jest opcja Only files needed to run application. Sęk w tym, że pliki, dla których właściwość Build Action ma wartość None nie są traktowane jako niezbędne do działania aplikacji i zostaną pominięte w czasie kopiowania. Oczywiście skończy się to komunikatem o błędzie przy pierwszej próbie wczytania pliku. Problem jest bardzo prosty do rozwiązania, wystarczy ustawić Build Action na Content, ale łatwo o tym zapomnieć w ferworze kodowania.

Trojanie

Home

"Trojanie" to opera Hectora Berlioza, którą można zobaczyć na deskach Teatru Wielkiego. Bilety na nią wpadły mi w ręce trochę przypadkiem, a decyzję czy iść musiałem podjąć bardzo szybko i mówiąc szczerze miałem pewne wątpliwości. Bynajmniej nie dlatego, że na słowo opera cierpnie mi skóra ale dlatego, że 5 godzinne przedstawienie tuż po pracy, nastrojowa muzyka, przygaszone światła... skłaniają do drzemki. Pomimo początkowych wątpliwości zdecydowałem, że skorzystam z okazji i nie żałuję. Powiem nawet więcej, jestem bardzo zadowolony z podjętej decyzji i szczerze zachęcam każdego do kupna biletów na to wspaniałe widowisko przy następnej nadarzającej się okazji.

Czemu ta opera opowiadająca o bitwie o Troję i dalszych losach jej mieszkańców jest tak wyjątkowa? Orkiestra, dyrygent, aktorzy, tancerze, śpiewacy byli wspaniali, zresztą innych w Teatrze Wielkim się nie zobaczy, ale mnie zachwyciła przede wszystkim scenografia. Co tu dużo mówić momentami zbierałem szczękę z podłogi!

Niech wspomnę o kilkudziesięciu szturmowcach Imperium w charakterystycznych białych zbrojach, walce bokserskiej, koniu trojańskim zbudowanym z laptopów, kosmonautach, aktorach/statystach unoszących się w powietrzu i Elvisie... Takich rzeczy nie widuje się codziennie, a już na pewno nie w operze!

W bardzo ciekawy sposób wykorzystano animację komputerową. Tło ogromnej sceny stanowił jeden ekran (kurtyna), a drugi, przezroczysty w 90% został umieszczony z przodu sceny, pomiędzy widownią i aktorami. Na obu ekranach wyświetlano to samo np.: kłębowisko węży, statki kosmiczne... Wykorzystanie dwóch ekranów pozwoliło wywołać efekt przestrzenności. Trudno to opisać ale wyglądało super. W kilku animacjach udało mi się nawet dostrzec słynny Blue Screen of Death. Z animacją bardzo fajnie współgrała dekoracja. Momentami można było się pogubić co jest wyświetlane na ekranie, a co znajduje się na scenie. Moje uznanie wzbudziła też scena, w której kilkanaście osób buduje jeden wielki ekran złożony z kilkunastu zsynchronizowanych laptopów.

Cała opera ogólnie przepełniona jest różnymi nawiązaniami do popkultury i współczesnego zinformatyzowanego świata. Na scenie cały czas coś się dzieje i naprawdę ciężko się nudzić. Jeszcze raz polecam!

Co to jest?!?!?!

Home

Co to jest?!?!?!. Kiedyś otrzymałem mail o takim właśnie tytule, a zawierający fragment mojego kodu. Kod ten, przyznam szczerze, zbyt elegancki nie był, ale napisałem go w sytuacji rodzaju "Masz to napisać na wczoraj". Ważne, że działał i robił to co miał robić. Nie jestem człowiekiem, który uważa swój kod za święty i sądzę, że umiem przyjąć krytykę, ale ten mail nie spodobał mi się z kilku powodów.

Po pierwsze oprócz mnie został wysłany do dwóch innych osób. Po drugie w kodzie zamieściłem komentarz wyjaśniający co ten krótki fragment kodu robi. Po trzecie treść wiadomości nie zawierała żadnych wyjaśnień jak to zrobić lepiej. Innymi słowy celem tego maila było nie tyle zwrócenie mi uwagi, że coś zrobiłem nie tak, ale bardziej pokazanie innym, że coś robię nie tak.

Całą sytuację nie przejąłem no bo i po co. Na "zaczepki" tego rodzaju mam w zwyczaju nie odpowiadać chyba, że się powtarzają. Kilka godzin później otrzymałem jednak wiadomość od jednej z dwóch osób, do której skierowany był mail Co to jest?!?!?!. Wiadomość ta była skierowana bezpośrednio do autora wiadomości Co to jest?!?!?! i wyglądała mniej więcej tak:

A to CO TO JEST?!?!?!:

1. Opis błędu numer 1.
2. Opis błędu numer 2.
3. ....

Opis błędów wskazywał, że autor kodu poprzestał tylko na jego skompilowaniu i nawet jeden raz go nie uruchomił. Jak mówi stare przysłowie kto mieczem wojuje ten od miecza ginie. Krytyka jest potrzebna i często wskazana, ale krytykować trzeba umieć. Ja kiedy napotkam jakiś błąd w cudzym kodzie to trzymam się kilku zasad:

1. Nie krytykuję publicznie czyli wysyłam mail tylko do jednej osoby. Jeśli rozmawiam z osobą, w której kodzie znalazłem błąd to mówię jej o tym w dyskretny sposób.
2. Jeśli widzę, że błąd jest powszechnie popełniany to wysyłam maila to potencjalnie zainteresowanych osób i pokazuję przykład błędnego kodu ale nie wskazuję kto go napisał.
3. Krytykując staram się zawsze wyjaśnić czemu uważam, że coś jest zrobione źle i jak to zrobić lepiej.
4. Staram się aby moja wiadomość/wypowiedź nie była odebrana jako atak. Na przykład zamiast sformułowania Co to jest?!?!?! mail zatytułowałbym Błąd w metodzie SomeMethod. Taki tytuł wiadomość niesie z sobą jakąś informację i sądzę, że jest neutralny w odbiorze.
5. Zanim wyślę maila lub pójdę porozmawiać upewniam się jeszcze raz, że błąd to rzeczywiście błąd.

Publiczna krytyka niestety jest czasem potrzebna, ale tylko w "beznadziejnych" przypadkach czyli wtedy kiedy ktoś zupełnie ignoruje nasze uwagi.

Życzenia świąteczne

Home

Z okazji Świąt Bożego Narodzenia składam czytelnikom i czytelniczkom bloga serdeczne życzenia wszystkiego najlepszego oraz wybiegając trochę w przyszłość życzę dużo szczęścia i pomyślności w nadchodzącym nowym roku.

Pozdrawiam
Michał Komorowski