Jak zakończyć raz na zawsze spory o formatowanie kodu?

Czytelność kodu ma znaczenie. Kto nie wierzy, niech poczeka aż będzie trzeba przeczytać i zrozumieć czyjeś (także swoje…) bazgroły sprzed paru lat, sformatowane w cały świat. Kod jest dużo częściej czytany niż pisany, a bez zrozumienia nie powinno być mowy o wprowadzaniu jakichkolwiek zmian.

Ten artykuł został napisany gościnnie przez Sebastiana Buczyńskiego – Expert developera z STX Next, który prowadzi własnego bloga breadcrumbscollector.tech oraz pisze książkę o Czystej Architekturze

Nie tak łatwo mieć dobrze sformatowany kod

Z formatowaniem kodu łączą się głównie dwa wyzwania – wypracowanie zasad stylu w zespole oraz ich spójne stosowanie w projekcie. Oba niestety mocno zależą od człowieka, co jest problemem. Każdy członek najpewniej ma już własny bagaż doświadczeń i ulubiony sposób na formatowanie.

Samo dojście do konsensusu, jeżeli mamy do czynienia z przerostem ego u niektórych, może być czasochłonnym i niepotrzebnie stresującym procesem. Jedną z popularniejszych „dyscyplin” jest udowadnianie wyższości spacji nad tabami albo jednego szczególnego sposobu stawiania nawiasów klamrowych nad innymi. Zaryzykuję stwierdzenie, że komputerowi jest wszystko jedno, a człowiek się przyzwyczai – byle w projekcie było spójnie. Swoją drogą, Python oszukał system, bo nie używa klamr, tylko bazuje na wcięciach :) Z drugiej strony, często dochodzi do komicznego sporu o maksymalną długość linii kodu.

Sytuacja została trocę poprawiona przez opublikowanie wytycznych formatowania dla danych języków – na przykład w PHP mówimy o PSR, a w Pythonie rządzi PEP8. Te dokumenty rozwiązują część dylematów. Pozostałe są przedmiotem typowego bike-sheddingu, czyli po polsku zajmowania się nieistotnymi pierdołami zamiast właściwą pracą.

Nawet jeżeli uda się wyprocować wspólne modus operandi, to pozostaje jeszcze kwestia jego egzekwowania. Często odbywa się to ręcznie podczas code review, co jest suboptymalne z dwóch powodów:

• formatowanie sprawdza człowiek, który jest stworzeniem omylnym,
• pomyłka jest wykrywana bardzo późno.

Jeżeli pracujemy zwinnie jako zespół i chcemy mieć czas na wartościową pracę, nie możemy sobie pozwolić na potykanie się o takie byle co. Blokada pull requesta przez problemy tego kalibru powoduje mierzalne, kilku(nasto)godzinne opóźnienia. Dodatkowo obniża wartość code review – jeżeli musimy skupiać się na sposobie w jaki ktoś stawia spacje, to dużo trudnej jest dostrzec zasadniczą treść danego pull requesta.

Formatery kodu – długo oczekiwane wybawienie?

Jeżeli jakiś proces jest zależny od człowieka (a więc z definicji jest zawodny) oraz podlega automatyzacji, to najpewniej należy pozbawić ludzi konieczności zajmowania się nim. Nie inaczej jest z formatowaniem kodu! Okazuje się, że istnieją narzędzia, które formatują kod automatycznie.

Posiadanie takiego narzędzia całkowicie eliminuje problem z egzekwowaniem jednolitego stylu. Po pierwsze, formater można umieścić w procesie continous integration, by automatycznie sprawdzał formatowanie kodu i zwalniał z tego programistów. Po drugie, developer może skonfigurować narzędzie lokalnie tak, by nigdy nie wypuścić ze swojej maszyny kodu, który nie jest sformatowany jak należy.

Co do problemu z wypracowaniem zasad stylu, wiele formaterów po prostu narzuca swój styl i nie mo możliwości konfiguracji. Może i brzmi to na drastyczne rozwiązanie, ale przynajmniej niczyje przerośnięte ego, przyzwyczajenia, czy preferencje nie muszą wpływać na pracę innych ludzi. Doskonale odzwierciedla to jedno z przysłów Go:

Gofmt’s style is no one’s favorite, yet gofmt is everyone’s favorite.

W Go formater gofmt jest integralną częścią języka. Powyższe powiedzonko w wolnym tłumaczeniu: pomimo tego, że styl na jaki formatuje gofmt nie jest niczyim ulubionym, to każdy docenia zalety automatycznego formatowania kodu.

Używanie formatera w codziennej pracy

na przykładzie Pythona i formatera black

Istnieje kilka sposób na zintegrowanie fomatera z naszym codziennym workflow. Od razu powiedzmy, że nie zadowala nas ręczne uruchamianie formatera po skończonej pracy – chcemy by działo się to w jak najmniej intruzywny, nienatarczywy sposób.

1. git pre-commit hook

Prosty sposób na szybsze dowiedzenie się, że coś jest nie tak przed wypchnięciem kodu do repozytorium. W katalogu głównym projektu odszukujemy ukryty folder .git, a w nim hooks, by dotrzeć do pliku pre-commit. (.git/hooks/pre-commit). Jeżeli nie istnieje, trzeba go stworzyć i nadać mu prawa do wykonywania (chmod +x). W środku umieszczamy:

set -e

black ./ --check

Od teraz nie uda nam się stworzyć commita, jeżeli nasz kod nie będzie spełniał formatu blacka. To miłe dowiedzieć się o tym zanim wypchniemy kod, ale powinno być traktowane raczej jako ostatnia linia obrony na komputerze developera niż ostateczne rozwiązanie.

2. integracja ze swoim edytorem/IDE

Drobnym krokiem naprzód w stosunku do ręcznego uruchamiania blacka może być umieszczenie polecenia z nim pod kombinacją klawiszy w naszym IDE, np. PyCharmie.

Następnie możemy już wywoływać formater z poziomu menu Tools -> External Tools -> Black. Warto skonfigurować sobie skrót klawiszowy pod Settings -> Keymap -> External Tools, aby uniknąć zbędnego klikania.

Korzystne jest skonfigurowanie skrótu klawiszowego pod Settings -> Keymap -> External Tools.

Jeszcze mniej wymagająca od programisty integracja zakłada, że nasze IDE będzie automatycznie wykonywać Blacka każdorazowo po zapisie pliku (co środowiska z rodziny Intellij robią praktycznie cały czas podczas edycji). W tym wypadku trzeba posłużyć się wtyczką FileWatcher – szczegóły w dokumentacji Blacka.

Nie korzystam z Pythona. Co ze mną?

Nie pozostaje nic innego, jak pogooglowanie za formaterem odpowiednim dla swojego środowiska. Nadal można jednak wykorzystać wskazówki podane powyżej do integracji wybranego narzędzia ze swoim IDE/edytorem kodu.

Styl blacka nie podoba mi się. Co robić?

Po pierwsze pamiętać, że subiektywne „lubienie” czy „podobanie się” nie są metodykami odpowiednimi dla inżynierów ;) Po drugie, istnieją co najmniej dwie inne możliwości:

• autopep8 – formater bazujący na pycodestyle i PEP8
• yapf – rozbudowany formater, z możliwością szczegółowej konfiguracji

Zakończenie

Odpowiadając na pytania zadane w tytule – jak zakończyć raz na zawsze spory o formatowanie kodu – wystarczy wyeliminować człowieka z procesu. ;) Maszyna sprawdzi się lepiej, gdyż jest doskonała w robieniu powtarzalnych rzeczy, nie męczy się, nie odpuści nikomu i zawsze będzie formatować zgodnie z wytycznymi.

Ten artykuł został napisany gościnnie przez Sebastiana Buczyńskiego – Expert developera z STX Next, który prowadzi własnego bloga breadcrumbscollector.tech oraz pisze książkę o Czystej Architekturze