Code review a czytelność kodu

06.11.2023 | Sławomir Parysz

Wstęp

Zauważyliśmy w naszym zespole, że w procesie code review często były zgłaszane te same uwagi stylistyczne, które bezpośrednio przekładają się na czytelność kodu. Każdy z programistów ma swoje preferencje oraz przyzwyczajenia jeśli o to chodzi, co powodowało częste dyskusje w zespole. Zaczęliśmy szukać rozwiązania, które ustandaryzowałoby nasze przyjęte konwencje czytelności kodu, najlepiej takie, które byłoby zautomatyzowane. To wszystko po to, aby oszczędzić czas oraz skupić się na rzeczach o większej istotności podczas przeglądu kodu. Ale najpierw odpowiedzmy sobie na pytanie.

 

Czym jest code review?

Code review, czyli po polsku przegląd kodu, głównie ma na celu sprawdzenie zmian w kodzie pod kątem identyfikacji potencjalnych błędów, zwiększenia jakości kodu oraz rozprzestrzeniania wiedzy w zespole. Jest to ważny krok w procesie wytwarzania oprogramowania, aby pozyskać opinię na temat przyjętego rozwiązania i wybranej implementacji, zanim wrzucimy nasz kod na produkcję. Wypracowanie solidnego procesu przeglądu kodu stanowi podstawę do ciągłego doskonalenia oraz zapobiega klienta przed niestabilnym kodem.

Możemy wymienić co najmniej kilka plusów tego procesu:

• Wymiana wiedzy w zespole
• Wcześniejsze wykrywanie błędów
• Zachowanie zgodności ze standardami
• Zwiększenie jakości oraz bezpieczeństwa kodu
• Zwiększa współpracę i świadomość w zespole

Niestety code review wymaga czasu naszych kolegów i koleżanek. Wydłuża on także czas wydania funkcjonalności klientowi. Im kod mniej czytelny tym więcej czasu poświęcamy na ten proces. Naszym celem zatem jest maksymalne skrócenie czasu tego procesu poprzez eliminację i ustandaryzowanie stylistyki pisanego kodu. Taki kod także szybciej i przyjemniej się czyta. Tym samym też większe skupienie jest na wyszukiwaniu błędów oraz poprawy jakości i bezpieczeństwa kodu.

 

Jak to zrobiliśmy?

Ustalanie takich reguł wcale nie jest proste i szybkie jak mogłoby się wydawać. Jest to proces ciągły, wymagający dobrej komunikacji w zespole, sporo spotkań oraz rozmów. Najlepiej robić to stopniowo, przy okazji. Jeśli ktoś natknie się na przypadek do omówienia podczas przeglądu kodu - omawiamy go na kolejnym daily lub spotkaniu architektonicznym. Przegląd kodu u nas odbywa się w momencie wystawienia pull requesta w Azure DevOps. Następnie musieliśmy wybrać rozwiązania, które pomogą nam w tym. Jesteśmy zespołem pracującym w .NET, dlatego posłużę się w tym artykule przykładem co możemy wykorzystać w Microsoft Visual Studio. W pierwszej kolejności możemy skorzystać z wbudowanych rozwiązań.

 

EditorConfig

W Visual Studio możemy ustawiać swoje własne preferencje stylu kodu w Options > TextEditor > C# > Code Style > General. 

Źródło: dokumentacja Microsoft https://learn.microsoft.com/en-us/visualstudio/ide/code-styles-and-code-cleanup?view=vs-2022

 

Opcje ustawione w tym miejscu mają zastosowanie do programu Visual Studio i nie są powiązane z konkretnym projektem. Ponadto nie są sprawdzane podczas budowania projektu czy procesie Continous Integration. Jeśli chcemy powiązać preferencje stylu kodu z konkretnym projektem lub solucją - musimy dla niego wygenerować plik .editorconfig. Możemy to zrobić manualnie lub automatycznie za pomocą przycisku „Generate .editorconfig file from settings” na podstawie naszych wcześniej zdefiniowanych preferencji wyżej wskazanych na zrzucie lub za pomocą menu rozwijalnego klikając prawym przyciskiem myszy na projekcie.

Źródło: Opracowanie własne

 

Ustawienia w pliku EditorConfig pozwalają zachować spójne standardy kodowania. Dotyczą one:

1. Whitespace, czyli wyglądu plików, w tym między innymi: wcięć i odstępów, preferencji co do nowych linii, preferencji przerw między elementami
2. Code style, czyli styli dotyczących bloków kodu, wyrażeń, modyfikatorów dostępu, nowych linii, preferencji co do sprawdzania nulli czy używania polecenia var
3. Naming style dotyczące nazewnictwa interfejsów, zmiennych
4. Analyzers, czyli zestaw microsoftowych zasad pisania kodu podzielone na wiele podkategorii takie jak: Design rules, Maintainability rules, Naming rules, Performance rules, Rebialility Rules, Security Rules i inne. 

Źródło: opracowanie własne

 

Każda z opcji może mieć ustawiony jeden z czterech dostępnych wartości: Disabled, Suggestion, Warning oraz Error. Suggestion będzie podkreślać kod w edytorze. Ciekawsze zastosowanie ma Warning oraz Error. Jeśli je ustawimy to w czasie kompilacji naruszenia stylu kodu będą wyświetlane jako ostrzeżenia lub błędy z prefiksem "IDE". Umożliwia to ścisłe egzekwowanie spójnego stylu kodowania.

Co ciekawe ustawienia z tego pliku są obsługiwane przez wiele edytorów kodu oraz IDE. Jest to przenośny komponent i podróżuje razem z repozytorium kodu. Pełną listę wspieranych edytorów można znaleźć na stronie https://editorconfig.org/. 

 

Code Cleanup

Kolejnym rozwiązaniem, które proponuje Microsoft jest Code Cleanup. Skonfigurować go można wybierając Analyze > Code Cleanup > Configure Code Cleanup.

Źródło: opracowanie własne

 

Mamy możliwość skonfigurowania dwóch profili. Wybór opcji jest dosyć spory i szeroki. Znajdziemy tutaj takie ustawienia jak: usuwanie nieużywanych zmiennych, parametrów, usingów, oznaczanie pól jako readonly, preferencje dotyczące tworzenia obiektów, weryfikacji czy przestrzenie nazw są zbieżne z miejscem w folderze, formatowania dokumentu. Jest nawet opcja do wyprowadzenia wszystkich ostrzeżeń i błędów ustawionych w EditorConfig oraz wiele, wiele więcej. Większość ustawień czyszczenia kodu jest mapowana na jeden lub więcej stylów kodu .NET obsługiwanych w .editorconfig.

Źródło: opracowanie własne

 

Zobaczmy czy istnieją jeszcze inne rozwiązania pomagające utrzymać standard pisania kodu.

 

CodeMaid

Jednym z najpopularniejszych dodatków do Visual Studio jest CodeMaid, który jest projektem open source. Dzięki niemu możemy wyczyścić i uprościć kod napisany w językach: C#, C++, F#, VB, PHP, PowerShell, R., JSON, XAML, XML, ASP, HTML, CSS, LESS, SCSS, JavaScript oraz TypeScript.

 Za jego pomocą możemy między innymi:

• Usunąć nieużywane instrukcje using oraz posortować je
• Dodać puste linie między instrukcjami/metodami jeśli ich brak
• Usunąć nadmiarowe puste linie, białe znaki, znaki końca linii
• Uruchomić formatowanie ustawione w Visual Studio

Czyszczenie kodu może być uruchamiane automatycznie po zapisaniu, lub na żądanie. Może być uruchamiane na pojedynczym pliku, wszystkich otwartych plikach, dowolnym wyborze w eksploratorze plików lub na całej solucji.

Źródło: opracowanie własne

 

To tylko część jego możliwości. Poza czyszczeniem kodu możemy także uruchomić widok „CodeMaid Spade” za którego pomocą nawigujemy po otwartym pliku C# z poziomu widoku drzewiastego. Poprzez przeciągnij i upuść możemy przesuwać całe kawałki kodu w pliku, sortować plik po typach, czyli polach, konstruktorach, metodach i tak dalej.

Źródło: dokumentacja CodeMaid https://www.codemaid.net/documentation/

 

Każdą z tych funkcjonalności można szeroko konfigurować w ustawieniach dodatku. Możemy wskazać które rozszerzenia plików mają być brane pod uwagę. Jeśli chodzi zaś o opcje czytelności kodu, na zdjęciu poniżej przykład ustawiania opcji „Insert”, czyli wstawiania pustych linii, przed i poza kawałkami kodu, wstawiania spacji, czy modyfikatorów dostępu.

Źródło: dokumentacja CodeMaid https://www.codemaid.net/documentation/

 

 

Przypadek użycia

Zobaczmy na przykładzie prostego pliku ile i jak bardzo zmienia się czytelność kodu po zastosowaniu tych rozwiązań.

Plik przed.

Źródło: opracowanie własne

Plik po.

Źródło: opracowanie własne

 

Zostały wykonane następujące czynności podczas zapisania pliku:

1. Zostały usunięte nieużywane usingi oraz posortowane używane
2. Został poprawiony konstruktor
3. Została usunięta zbędna pusta linia
4. Została dodana brakująca pusta linia oddzielająca metody
5. Zostały usunięte zbędne spacje
6. Zostały poprawione wcięcia
7. Zostały usunięte nadmiarowe linie na końcu pliku. 

Automatyzacja

Na tym etapie mamy skonfigurowane w narzędziu pryncypia dotyczące czytelności kodu. Jak natomiast je stosować? Najlepiej gdyby odbywało się to w tle, bez naszej ingerencji, bez pamiętania o tym przy modyfikacji każdego pliku z osobna. Na szczęście możemy to zautomatyzować. Jest możliwość uruchomienia pryncypiów przy zapisywaniu zmian w dokumencie.

Jeśli chodzi o plik .editorconfig, to po dodaniu pliku do projektu, każda kolejna napisana linijka kodu będzie sformatowania na podstawie jego ustawień. Istniejący kod w projekcie nie jest zmieniany, chyba, że zostanie uruchomiony jedno z następujących poleceń:

• Code Cleanup (Ctrl+K, Ctrl+E), które stosuje wszystkie ustawienia, lub
• Edit > Advanced > Format Document, które stosuje tylko ustawienia “whitespace”.

Jeśli chodzi o Code Cleanup wystarczy zaznaczyć opcję „Run Code Cleanup profile on Save” w Options > Text Editor > Code Cleanup oraz wybrać profil.

Źródło: opracowanie własne

 

Jeśli chodzi o dodatek CodeMaid możemy to zrobić w jego ustawieniach zaznaczając opcję „Automatically run cleanup on file save” lub użyć skrótu Ctrl+M, ‘.

Źródło: opracowanie własne

 

Podsumowanie

Na rynku istnieje wiele rozwiązań poprawiających czytelność kodu, także płatnych. Niezależnie w jakim języku programowania piszecie na pewno znajdziecie odpowiednie narzędzia dla siebie. Mając zdefiniowane reguły czytelności kodu na poziomie zespołu, przy procesie przeglądu kodu możemy w końcu skupić się na tym co najważniejsze. Zastosowanie takich zasad przyśpieszyło wykonywanie przeglądu kodu w naszym zespole do czego Was także bardzo zachęcam.