Przerwa kawowa #20. Co to jest starszy kod i jak z nim pracować. Narzędzia ułatwiające pisanie dokumentacji technicznej

Co to jest starszy kod i jak z nim pracować

Źródło: Dou Wcześniej czy później programista prawdopodobnie będzie musiał zetknąć się ze starszym kodem. Aby złagodzić konsekwencje tej znajomości, wybrałem kilka praktycznych wskazówek i przykładów z własnego doświadczenia - zwłaszcza pracy ze starszym systemem Java.

Starsze funkcje

Legacy to cudzy kod, który często jest tak okropny, że ogólnie nie jest jasne, jak z nim pracować. A jeśli będziesz musiał pracować ze starszym systemem, oprócz starego kodu, napotkasz także:

• z przestarzałą technologią;
• architektura heterogeniczna;
• brak lub wręcz całkowity brak dokumentacji.

W rzeczywistości stary kod nie jest taki straszny i oto dlaczego: jeśli system przetrwał te dziesięć lat i nadal działa, to ma pewne zastosowanie. Może zarabia dobre pieniądze (w przeciwieństwie do twojego ostatniego startupu). Ponadto ten kod jest stosunkowo niezawodny, jeśli był w stanie przetrwać tak długo w produkcji. Dlatego zmiany w nim należy wprowadzać ostrożnie. Przede wszystkim musisz zrozumieć dwie rzeczy:

1. Nie możemy lekceważyć systemu, który zarabia miliony lub jest dostępny dla tysięcy ludzi dziennie. Nieważne, jak słabo został napisany, ten obrzydliwy kod przetrwał do produkcji i działa 24 godziny na dobę, 7 dni w tygodniu.

2. Ponieważ ten system przynosi prawdziwe pieniądze, praca z nim wiąże się z dużą odpowiedzialnością. To nie jest startup, ale coś, z czym użytkownicy będą pracować jutro. To też wiąże się z bardzo wysokim kosztem błędu i nie chodzi tu o roszczenia klienta, a o faktyczny stan rzeczy.

Inżynieria odwrotna

Aby pomyślnie pracować ze starszym kodem, będziesz musiał zastosować techniki inżynierii wstecznej. Najpierw musisz uważnie przeczytać kod, aby dokładnie zrozumieć, jak on działa. Jest to obowiązkowe, ponieważ najprawdopodobniej nie będziemy mieli dokumentacji. Jeśli nie zrozumiemy toku myślenia autora, dokonamy zmian o nieprzewidywalnych konsekwencjach. Aby się przed tym uchronić, musisz także zagłębić się w sąsiedni kod. A jednocześnie poruszaj się nie tylko wszerz, ale także w głąb. Gdzie wywoływana jest metoda z błędem? Skąd pochodzi kod wywołujący tę funkcję? W starszych projektach „hierarchia wywołań” i „hierarchia typów” są używane częściej niż cokolwiek innego. Będziesz musiał spędzić dużo czasu z debugerem: po pierwsze, aby znaleźć błędy, a po drugie, aby zrozumieć, jak wszystko działa. Jeśli chodzi o dokumentację, nie byłoby złym pomysłem odwołanie się do archeologii przemysłowej. Bardzo przydatne może być odkopanie gdzieś starej dokumentacji i porozmawianie z tymi, którzy pamiętają, jak napisano odziedziczony kod. Stosując te techniki, prędzej czy później zaczniesz mniej więcej rozumieć kod. Aby jednak zapobiec zmarnowaniu wysiłków, należy natychmiast udokumentować wyniki swoich badań. W tym celu polecam rysowanie schematów blokowych lub diagramów sekwencji. Oczywiście będziesz leniwy, ale zdecydowanie musisz to zrobić, w przeciwnym razie za sześć miesięcy bez dokumentacji będziesz grzebał w tym kodzie, jakby to był pierwszy raz.

Nie przepisuj kodu

Najważniejszą rzeczą w procesie rozwoju jest bicie się na czas i nie próbowanie przepisywania całego kodu od zera. Oszacuj, ile osobolat będzie to wymagało. Jest mało prawdopodobne, aby klient chciał wydać tak dużo pieniędzy na przeróbkę czegoś, co już działa. Dotyczy to nie tylko systemu jako całości, ale także dowolnej jego części. Oczywiście mogą dać ci tydzień na przemyślenie wszystkiego i kolejny tydzień na naprawienie czegoś. Ale jest mało prawdopodobne, że dadzą ci dwa miesiące na ponowne napisanie części systemu. Zamiast tego zaimplementuj nową funkcjonalność w tym samym stylu, co reszta kodu. Innymi słowy, jeśli kod jest stary, nie powinieneś ulec pokusie użycia nowych, pięknych technologii: taki kod będzie wtedy bardzo trudny do odczytania. Na przykład możesz spotkać się z sytuacją taką jak my: część systemu jest napisana w Spring MVC, a część w gołych serwletach. A jeśli w części napisanej w serwletach trzeba dodać coś jeszcze, to dodajemy to w ten sam sposób - w serwletach.

Szanuj interesy biznesowe

Należy pamiętać, że o wszelkich zadaniach decyduje przede wszystkim wartość dla biznesu. Jeśli nie udowodnisz klientowi konieczności pewnych zmian z biznesowego punktu widzenia, zmiany te nie nastąpią. A żeby przekonać klienta, trzeba spróbować stanąć na jego miejscu i zrozumieć jego zainteresowania. W szczególności, jeśli chcesz dokonać refaktoryzacji tylko dlatego, że kod jest trudny do odczytania, nie będziesz mógł tego zrobić i musisz z tym żyć. Jeśli naprawdę nie możesz tego znieść, możesz po cichu i stopniowo zreorganizować kod, rozkładając pracę na bilety biznesowe. Lub przekonaj klienta, że ​​to na przykład skróci czas potrzebny na znalezienie błędów, a co za tym idzie, ostatecznie obniży koszty.

Test

Oczywiste jest, że testowanie jest konieczne w każdym projekcie. Jednak pracując ze starszymi systemami, należy zwrócić szczególną uwagę na testowanie, również dlatego, że wpływ wprowadzonych zmian nie zawsze jest przewidywalny. Będziesz potrzebować co najmniej tylu testerów, co programistów, w przeciwnym razie powinieneś być niesamowicie dobry w automatyzacji. W naszym projekcie testowanie składało się z następujących etapów:

1. Weryfikacja, gdy zaimplementowana funkcjonalność funkcjonalności jest sprawdzana w osobnej gałęzi.
2. Stabilizacja, gdy sprawdzana jest gałąź wydania, w której wszystkie funkcje są ze sobą połączone.
3. Certyfikacja, gdy to samo jest uruchamiane ponownie na nieco innych przypadkach testowych w środowisku certyfikującym, które jest jak najbardziej zbliżone do produkcyjnego pod względem charakterystyki sprzętu i konfiguracji.

I dopiero po przejściu przez wszystkie te trzy fazy możemy dokonać uwolnienia. Ktoś pewnie myśli, że certyfikacja to dodatkowa faza, skoro wszystko zostało już wyjaśnione na etapie stabilizacji, ale nasze doświadczenie podpowiada, że ​​tak nie jest: czasami podczas testu regresyjnego, który jest uruchamiany w drugiej turze na innej maszynie, coś się jakoś dzieje okaże się.

Sformalizuj DevOps i wypuść

Procedura zwolnienia może na przykład wyglądać następująco. Po zakończeniu programowania i dwóch lub trzech fazach testowania piszemy e-mail do zespołu DevOps na 36 godzin przed oczekiwaną datą wydania. Następnie dzwonimy do zespołu devops i omawiamy wszelkie zmiany w środowiskach (informujemy ich o wszelkich zmianach w bazie danych i konfiguracji). Na każdą zmianę mamy dokument (bilet w Jira). Następnie, podczas wydawania wersji, wszyscy zaangażowani w to spotykają się i wszyscy mówią, co robią teraz: „Przesłaliśmy bazę danych”, „Uruchomiliśmy ponownie takie a takie serwery”, „Poszliśmy przeprowadzić testy regresyjne w środowisku produkcyjnym. ” Jeśli coś pójdzie nie tak, uruchamiana jest procedura wycofywania wydań, dokładnie opisana w oryginalnym dokumencie wydania - bez takiego dokumentu na pewno o czymś zapomnimy lub się pogubimy.

Kontroluj jakość kodu

I wreszcie przegląd kodu to praktyka, która z jakiegoś powodu nie jest stosowana we wszystkich projektach. Świetnie jest, jeśli każdy fragment kodu jest sprawdzany przez więcej niż jedną osobę. Nawet w bardzo silnym zespole niektóre błędy zawsze zostają wykryte podczas procesu przeglądu kodu, a jeśli przyjrzy się temu kilka osób, liczba zidentyfikowanych błędów wzrasta. Co więcej, czasami trzeci lub czwarty recenzent znajduje najgorszą rzecz.

Narzędzia ułatwiające pisanie dokumentacji technicznej

Źródło: Dzone Większość programistów nie lubi pisać dokumentacji technicznej. Ekspert w dziedzinie psychologii Gerald Weinberg nazwał nawet dokumentację „olejem rycynowym programowania”: programiści uwielbiają ją czytać, ale po prostu nienawidzą jej samodzielnego pisania. Brak wskazówek lub pusty plan działania skutkuje brakiem informacji o tym, jak działają różne części oprogramowania. Ostatecznie pogarsza to komfort użytkowników końcowych kodu, ponieważ w przypadku braku dokumentacji nie mogą oni polegać na dokładności i użyteczności produktu. Aby ułatwić programistom wyrobienie nawyku pisania dokumentacji, polecam zwrócić uwagę na cztery doskonałe narzędzia, które są obecnie dostępne niemal dla każdego.

Strony GitHuba

Prawdopodobnie nie ma dziś ani jednego programisty, który nie miałby doświadczenia w pracy na GitHubie. To także świetne miejsce dla programistów, którzy potrzebują miejsca do przechowywania dokumentacji. Wiele osób korzysta ze standardowego pliku Readme w swojej bazie kodu, aby zapewnić użytkownikowi prosty przewodnik z instrukcjami, ale nie jest to jedyny sposób tworzenia dokumentacji w GitHub. Dzięki GitHub Pages zyskujesz więcej niż tylko hosting stron swojego projektu, w tym dokumentację i samouczki. Otrzymujesz możliwość bezpośredniej interakcji ze wszystkimi repozytoriami GitHub, umożliwiając programistom aktualizację dokumentacji w taki sam sposób, w jaki aktualizują swój kod. Co więcej, możesz tutaj użyć Jekylla - pomaga on przekształcić znaczniki w zwykły tekst lub w pełnoprawne strony internetowe.

Przeczytaj Dokumentację

Jak sama nazwa wskazuje, Read the Docs zapewnia programistom platformę do przechowywania i czytania dokumentacji. Usługa działa podobnie jak GitHub Pages: programiści mogą wprowadzać zmiany w dokumentacji ze swoich ulubionych systemów kontroli wersji, w tym Git, Bazaar, Mercurial i innych. Obsługiwane jest również automatyczne wersjonowanie i tworzenie stron. Najlepszą częścią Read Docs jest jego elastyczność. Obsługuje webhooki, dzięki czemu można zautomatyzować większość procesu tworzenia dokumentów. To ogromna oszczędność czasu przy zadaniu, z którym większość programistów nie chce mieć nic wspólnego. Ponadto wszystko, co znajduje się na platformie, jest dostępne dla ogółu społeczeństwa w różnych formatach, w tym PDF, jednostronicowy HTML, a nawet w formacie e-booka. Serwis przejmuje znaczną część rutynowych prac związanych z utrzymaniem aktualności dokumentacji.

Tettra

Tettra to nie tylko platforma do przechowywania dokumentacji oprogramowania, ale kompletna baza wiedzy. Sprawdza się to szczególnie dobrze, gdy w projekt zaangażowana jest duża grupa programistów pracujących nad różnymi fragmentami oprogramowania. Tettra może służyć do dokumentowania odpowiedzi na często zadawane pytania.

Pasieka

To, co sprawia, że ​​Apiary jest tak przydatna dla programistów, to fakt, że świetnie pomaga w dokumentacji API. Platforma umożliwia użytkownikom pisanie dokumentacji w Markdown , w tym próbnych wywołań API. Pasieka umożliwia także testowanie i prototypowanie elementów API. Inaczej mówiąc, jest to narzędzie dokumentacyjne i platforma testowa w jednym miejscu.