Komentarze bannerowe - jak i dlaczego warto je wstawiać

Zawsze znajdzie się coś, co szczególnie zwróci Twoją uwagę pierwszego dnia w pracy. Dla mnie było to stanowisko pracy inżyniera, który siedział za mną. Miał trzy monitory (oczywiście jeden w orientacji pionowej), mechaniczną klawiaturę, futurystyczną mysz, ogromne słuchawki.

Jednak nie ten arsenał najbardziej mnie zaintrygował. Zauważyłem coś nietypowego w jego kodzie - coś, co wyglądało prawie jak sztuka.

Sztuka w kodzie? Właśnie to widziałem na monitorach tego inżyniera za każdym razem, gdy się odwracałem! Zapytałem go, z czym ma do czynienia i usłyszałem wyjaśnienie.

Jest kilka miesięcy później i teraz to ja wyjaśniam tę sztukę w moim kodzie innym kolegom. I chcę się tym podzielić również z Tobą. To, co każę wrzucić do kodu, może wyglądać trochę jak WordArt, ale jest to coś więcej, obiecuję! 

Czym są?

Nazywam je banner comments lub blocky block comments. Kluczem jest duży, blokowy tekst, który jest komentarzem. Może powinienem to nazywać wielkim komentarzem blokowym?

Co dają?

Spójrzmy na zalety tego rozwiązania.

Lepsza organizacja kodu

Głównym powodem, który zachęca do korzystania z banner comments, jest poprawa czytelności i organizacji kodu. Użyj ich do podzielenia go na logiczne części. W przypadku aplikacji Express, napisanej w TypeScript, mogę utworzyć sekcje takie jak Types, Constants, Initialization, Routes, Helpers itp.

Oczywiście chcesz zmodularyzować swój kod i podzielić niektóre z tych sekcji na własne pliki, ale wszystkiego nie oddzielisz. Te komentarze pomogą Ci zrobić wyraźne sekcje w jednym pliku.

Łatwiejsza nawigacja w kodzie

Być może już teraz tworzysz podziały w kodzie za pomocą standardowych komentarzy. Tym samym wiesz, że znalezienie jednego komentarza może być naprawdę trudne, gdy przewijasz kod w postaci ściany tekstu. Dużego komentarza blokowego nie przegapisz tak łatwo!

Nie tylko łatwiej jest znaleźć kod podczas przewijania - banner comments działają świetnie w przypadku, gdy używasz minimapy. W mgnieniu oka przejdziesz do kodu, którego szukasz.

Upiększ swój kod i się wyróżnij

Każdy blocky block comment w Twoim kodzie jest arcydziełem. Pięknym, przemyślanym i ponadczasowym.

Dobrze, może przesadzam, ale uważam, że wyglądają naprawdę dobrze. Na pewno sprawią, że Twój kod będzie wyjątkowy i będzie się wyróżniał - a kto tego nie lubi? Dostałem do tej pory naprawdę sporo pytań od ludzi w pracy, którzy widzieli banner comments w moim kodzie. To świetny początek rozmowy.

Jak ich używać?

Mam nadzieję, że przekonałem Cię do myśli, że komentarze blokowe są świetne. Albo przynajmniej, że warto dać im szansę. Jak więc zacząć ich używać?

Tekst generujemy przez program o nazwie FIGlet, wydany po raz pierwszy w 1995 roku. Na oficjalnej stronie jest opisany jako „program do robienia dużych liter ze zwykłego tekstu”. W rzeczywistości FIGlet obsługuje setki różnych „czcionek”, chociaż większość z nich nie wygląda zbyt dobrze jako blokowe komentarze. Czcionka, której używam, nazywa się ANSI Shadow. Bardzo polecam tę czcionkę do tworzenia komentarzy właśnie tego typu.

Jak zapewne się domyślasz, możesz użyć narzędzia online do wygenerowania tekstu, a następnie skopiować go do swojego kodu. Jako leniwi programiści jesteśmy jednak o wiele bardziej wyrafinowani! Kto ma czas na przechodzenie do przeglądarki, wchodzenie na stronę, wpisanie tekstu i przeklejanie go do kodu?

Okazuje się, że dla prawie każdego większego IDE/edytora kodu, istnieje rozszerzenie do generowania tekstu przy pomocy FiGlet. Nie może już być łatwiej.

W przypadku VS Code uznałem ASCIIDecorator za najlepsze rozszerzenie. W przypadku Atoma wypróbuj rozszerzenie figlet. W przypadku dowolnego innego IDE/edytora, powinieneś być w stanie łatwo znaleźć odpowiednik. Jeśli jednak takowy nie istnieje, możesz użyć generatora online, interfejsu CLI lub spróbować samodzielnie napisać wtyczkę FIGlet.

Disclaimer

Banner comments wyglądają inaczej w zależności od motywu/czcionki/edytora. Przekonałem się, że wyglądają całkiem nieźle w większości edytorów, ale w niektórych miejscach, np. na GitHubie, prezentują się kiepsko. Oto proste porównanie:

/*
██████╗ ██╗      ██████╗  ██████╗██╗  ██╗██╗   ██╗
██╔══██╗██║     ██╔═══██╗██╔════╝██║ ██╔╝╚██╗ ██╔╝
██████╔╝██║     ██║   ██║██║     █████╔╝  ╚████╔╝ 
██╔══██╗██║     ██║   ██║██║     ██╔═██╗   ╚██╔╝  
██████╔╝███████╗╚██████╔╝╚██████╗██║  ██╗   ██║   
╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝   ╚═╝   
*/

/*
██████╗ ██╗      ██████╗  ██████╗██╗  ██╗██╗   ██╗
██╔══██╗██║     ██╔═══██╗██╔════╝██║ ██╔╝╚██╗ ██╔╝
██████╔╝██║     ██║   ██║██║     █████╔╝  ╚████╔╝ 
██╔══██╗██║     ██║   ██║██║     ██╔═██╗   ╚██╔╝  
██████╔╝███████╗╚██████╔╝╚██████╗██║  ██╗   ██║   
╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝   ╚═╝How it looks in a Medium code block. Not that you would ever do this.
*/

Podsumowanie

Podsumowując, uważam, że te komentarze są mi bardzo pomocne w organizacji kodu. I nie jestem w tym przekonaniu odosobniony - w mojej poprzedniej pracy zaczęliśmy wszyscy używać takich komentarzy. Wiele zespołów zdecydowało się na zaadoptowanie tego typu komentarzy, po zobaczeniu jak działają u mnie.

Prawdopodobnie już teraz robisz coś takiego w swoim kodzie:

/*
------------------------------------------------------------------
This is a comment that stands out!
But I hate making them.
I'm never consistent with the number of '-' characters I put.
And then the comment blocks are different sizes and look ugly.
And I'm too lazy to fix them.
So I just don't bother.
------------------------------------------------------------------
*/

Banner comments są zdecydowanie lepszą wersją takiego komentarza :)

Oryginał tekstu w języku angielskim przeczytasz tutaj.