Strona główna » Kursy » Kurs C++ » Formatowanie kodu
/**/
 

Formatowanie kodu

https://mattomatti.com/cp15

Wstęp

Pisanie kodu to nie tylko pisanie linijek kodu, tworzenie funkcji i ich testowanie. Wiąże się z tym jakość kodu. Do tego terminu nie zalicza się tylko efektywność kodu tj. czy program wykona n2 operacji czy tylko n·log(n). Kod powinien być czytelny zarówno dla komputera jak i dla człowieka. W przypadku pisania dla własnych potrzeb pomija się ten krok, ponieważ i tak nikt prócz mnie nikt z tego nie będzie korzystał. Czasem jednak zastosowanie zaledwie kilku drobnych wskazówek może pozwolić zaoszczędzić czas w przyszłości.

Przejrzystość kodu

Opisowe nazwy funkcji i zmiennych

Pierwszą bardzo ważną rzeczą, którą należy zastosować podczas pisania kodu to nazywanie zmiennych i funkcji w czytelny sposób. Przykładowo pisząc funkcję, która będzie dodawać dwie liczby warto nazwać np. suma(), a nie np. xyz(). Warto też pamiętać, że nazwa funkcji nie powinna być zbyt długa jak sumaDwochLiczb(). Szczegóły co dokładnie robi funkcja, albo jakie przyjmuje argumenty powinna trafić do dokumentacji. Ze względu na fakt, że w nazwie funkcji nie może być polskich znaków warto zastanowić się nad zastosowaniem angielskich nazw. W tym przypadku funkcja nazywałaby się sum(). Używanie angielskich nazw pozwoliłoby myśleć podczas pisania kodu tylko w jednym języku co mogłoby ułatwić używanie napisanych funkcji. Ponadto kod wtedy jest łatwiej udostępnić publicznie w Internecie dla wszystkich.

Wcięcia

Kolejnym krokiem, który zwiększa czytelność kodu jest zastosowanie wcięć w kodzie i pisanie każdej linijki kodu w oddzielnej linijce. Sposób wykorzystania tego zależy tylko i wyłącznie od programisty, ponieważ jest wiele różnych metod. Do najpopularniejszych metod jest użycie jako pojedynczego wcięcia 5 znaków spacji, albo znaku tabulacji. Mniej popularne choć spotykane są tylko 3 spacje. Z własnego doświadczenia uważam, że najlepszy znak tabulacji, ponieważ w dobrym środowisku programistycznym można dostosować szerokość tabulacji przez co łatwiej jest dostosować sposób wyświetlania kodu nawet innej osoby.

W celu zrozumienia zalety wcięć wystarczy spojrzeć na poniższy kod:

  1. int dodajnLiczb(int n) {
  2. int s = 0;
  3. for (int i = 1; i <= n; i++) {
  4. s += i;
  5. }
  6. return s;
  7. }

Powyższy kod jest zdecydowanie mniej czytelny niż poniższy. W drugim przykładzie łatwiej zauważyć, które linijki należą do wnętrza funkcji. Ponadto łatwiej znaleźć linijkę, która zawiera pętla for. Choć tutaj nie ma to większego znaczenia zmiana zmiennej s na suma pozwala łatwiej zrozumieć co wykonuje kod.

  1. int dodajnLiczb(int n) {
  2.   int suma = 0;
  3.   for (int i = 1; i <= n; i++) {
  4.     suma += i;
  5.   }
  6.   return suma;
  7. }

Styl pisania kodu i nazywanie zmiennych jest rzeczą całkowicie zależną od programisty np. podczas pisania kodu bardzo często używam i oraz j jako zmienne użyte w pętli i nigdy nie nazywam ich inaczej. Oczywiście należy pamiętać, że czasem może zajść potrzeba, aby podczas pracy w zespole lub podczas pisania biblioteki dostosować formatowanie kodu do środowiska dla którego / w którym się pisze.

Dokumentacja

Komentarze

W przypadku pracy zespołowej lub podczas udostępniania kodu online warto dopisać do programu coś na wzór dokumentacji. Zazwyczaj zastosowanie komentarzy dla mniejszych projektów jest wystarczające. Komentarze powinny pojawiać się przed funkcją tłumacząc co ona robi i jakie wartości przyjmuje dana funkcja. Dodatkowe komentarze mogą być dodane bezpośrednio w kodzie jako jednolinijkowe komentarze. Wyróżnia się dwa rodzaje komentarzy w środku kodu: pierwszy z nich ma za zadanie wytłumaczyć co robi dana linijka. Drugi typ komentarzy można traktować jako tytuły fragmentów i kodu. Ich głównym zadaniem jest poinformowanie inną osobę co w danej części wykonuje kod.

  1. /*
  2.   Program wczytuje od użytkownika zakres [a, b]
  3.   na podstawie argumentów oblicza sume wszystkich
  4.   liczb całkowitych w zakresie [a, b]
  5. */
  6. int main() {
  7.   // Wczytanie liczb
  8.   int a, b;
  9.   cin >> a >> b;
  10.   // Oblicz wynik
  11.   int w = 0;
  12.   for (; a <= b; a++)
  13.     w += a; // Dodaj kolejną liczbę z zakresu
  14.   // Wypisz wynik i zakończ program
  15.   cout << w << endl;
  16.   system("pause");
  17.   return 0;
  18. }

(1. - 5.) Poinformowanie programisty co wykonuje kod. Tutaj można dodać szczegółowe informacje co reprezentuje wybrany argument oraz jakie wartości przyjmuje. Komentarze w linijkach (7.), (10.), (14.) mają za zadanie podać co w danej części kodu jest wykonywane, a komentarz (13.) ma za zadanie poinformować co dokładnie robi dana linijka.

Należy pamiętać, że komentarz do każdej linijki może spowodować, że kod stanie się mało czytelny. Choć początkowo pewnie idea pisania komentarzy wydaje się niepotrzebna, ponieważ jak raz się napisze i działa to zawsze będzie działać nie zawsze jest prawdziwe. Zwykle podczas testowania programu znajduje się wartości argumentów dla których dana zwraca błędny wynik. Odpowiednie nazwanie części kodu pozwoliłoby na prostsze wyeliminowanie problemu podczas wczytywania / obliczania / wypisywania danych.

Dokładna dokumentacja

W przypadku większych projektów napisanie dokładniejszej dokumentacji jest bardzo ważne. W przypadku małych bibliotek można spędzić trochę czasu starając się zrozumieć jakie funkcje tam się znajdują i jak je zastosować. Jednak przy pisaniu bibliotek, zestawu narzędzi i innych projektów prosta wyszukiwarka i dokładny opis co robi funkcja oraz jakie przyjmuje argumenty jest bardzo ważne. Ponadto w dokumentacji napisanej oddzielnie łatwiej jest dodać przykłady opisujące zastosowanie funkcji w kodzie.

Dziennik zmian

W przypadku publicznego rozwijania kodu i zgłaszania wielu różnych problemów warto rozpocząć pisanie dziennika zmian (ang. changelog). Pozwoli to podczas wydanie nowej wersji zestawu narzędzi programistom szybko zapoznać się z wprowadzonymi zmianami. Dzięki temu łatwiej będzie im sprawdzić czy nie potrzebują wprowadzić zmian w swoim kodzie, aby zachować kompatybilność z nową wersją biblioteki.

Podsumowanie

Jak widać pisanie kodu to nie tylko pisanie linijek kodu, ale również ich opisywanie, a niekiedy nawet argumentowanie, dlaczego takie rozwiązanie najlepiej się sprawdzi dla podanej funkcji. Warto oczywiście pamiętać, że podczas pisania krótkich programów dla własnych potrzeb nie wymaga od razu pisania specjalnej dokumentacji, a komentarze mogą pojawić się w zaledwie kilku linijkach (jak nie w żadnej). Jednak podczas bardziej przydatnych funkcji warto dopisać kilka słów więcej komentarzy, aby łatwiej skopiować kod do nowego projektu i uniknąć wymyślania koła na nowo.