Formatowanie kodu

Formatowanie kodu – mniej lub bardziej sformalizowany zestaw reguł i zaleceń określający, jak powinien wyglądać kod źródłowy programu od strony jego czytelności i wyglądu. Wśród obszarów zainteresowania można wyróżnić np. zasady tworzenia wcięć czy nazewnictwo zmiennych i funkcji. Formatowanie kodu nie ma wpływu na sposób interpretacji lub kompilacji programu, lecz jest bardzo ważne dla programistów, którzy go rozwijają. Czytelność poszczególnych zasad jest subiektywna, dlatego nie istnieje jedna, uniwersalna konwencja. Ponadto, przyjęte reguły zależą od wybranego języka programowania.

W terminologii informatycznej wyróżnia się pojęcie styl kodowania, którym określa się nieformalne zbiory reguł, oraz standard kodowania będący formalnym dokumentem wdrożonym w konkretnym projekcie.

Znaczenie

W projektach zespołowych jednym z najważniejszych wymienianych powodów stosowania jednolitych reguł formatowania kodu są koszty utrzymania oprogramowania. We wstępie do opisu konwencji kodowania dla języka Java, firma Sun Microsystems wymieniła następujące fakty:

• 80% kosztów oprogramowania wynosi jego utrzymanie,
• jedynie nieliczne systemy są rozwijane ciągle przez jeden, niezmienny zespół programistów,
• konwencje formatowania kodu zwiększają jego czytelność, pozwalając na szybsze wdrożenie nowych inżynierów w prace nad rozwojem oprogramowania,
• jeśli sprzedajesz kod źródłowy jako produkt, musisz upewnić się, że jest on zaparkowany i czytelny tak, jak w przypadku innych produktów.

Sposób formatowania kodu ma także wpływ na niezawodność tworzonego oprogramowania — reguły mogą zabraniać stosowania zapisów, które mogą być mylące dla programistów, a także enigmatycznych nazw.

Formatowanie kodu ma wpływ na dodatkowe narzędzia analizy i przetwarzania kodu źródłowego. Programy takie, jak Doxygen czy javadoc wykorzystują informacje zawarte w komentarzach do generowania dokumentacji. W przypadku metryk oprogramowania bazujących na kodzie źródłowym, stosowanie jednolitej konwencji zwiększa dokładność pomiarów i umożliwia porównywanie poszczególnych fragmentów kodu.

Wpływ języka programowania

Mało jest uniwersalnych zasad formatowania kodu, które można stosować w każdym języku programowania. Przeważnie są one dostosowane do składni konkretnego języka. Języki mogą też wymuszać na programistach stosowanie określonych konwencji. Przykładem może tu być Python, gdzie wcięcia służą do tworzenia bloków kodu. Innym przykładem jest dostęp do elementów składowych obiektów z wnętrza ich metod — Java zezwala na pominięcie specjalnej referencji this, analizując kod i automatycznie decydując czy odwołujemy się do zmiennej lokalnej czy do pola obiektu, podczas gdy w PHP stosowanie zmiennej specjalnej $this jest wymagane.

Przykłady

W tej sekcji opisane są przykładowe elementy stylu formatowania kodu, najczęściej definiowane przez reguły:

Wcięcia

Wcięcia służą do szybkiej identyfikacji bloków kodu oraz wizualnej analizy przepływu sterowania. W poniższym przykładzie kodu języka C wystarczy rzut oka, by mieć ogólny obraz jego działania i zorientować się, jakie bloki kodu są ze sobą powiązane:

    if (warunek1) {
        while (warunek2)
            zrobCos();
        zrobCosJeszcze();
    } else {
        cosInnego();
    }

Przykład tego samego kodu źródłowego z niestarannym formatowaniem, który jest znacznie trudniejszy w lekturze:

    if (warunek)
               {
   while (warunek2)
              zrobcCos(); zrobCosJeszcze()
                             ;}else{cosInnego();
    }

Zasady formatowania definiują przede wszystkim:

• kiedy wcięcia należy robić, a kiedy nie,
• głębokość wcięć,
• znaki używane do tworzenia wcięcia (określona liczba spacji lub tabulacja).

Ograniczanie bloków kodu

W większości języków programowania blok kodu ograniczony jest przez określone słowa kluczowe (np. Pascal: begin ... end) lub symbole (np. C: { ... }). Jednocześnie, gramatyki tych języków pozwalają na ich pomijanie w pewnych szczególnych przypadkach, najczęściej gdy dany blok zawiera tylko jedną instrukcję. Z uwagi na popularność języków wywodzących się z C zwany jest on „zapisem bezklamrowym”. Styl formatowania kodu definiuje:

• czy słowo kluczowe bądź symbol rozpoczynający blok kodu pisany jest w nowej linijce, czy w tej samej,
• czy wolno stosować zapis bezklamrowy.

Przykład kodu w języku Pascal, w którym ograniczniki muszą być zapisywane w tej samej linijce i dopuszczalny jest zapis bezklamrowy:

for i := 1 to 10 do begin
   if i mod 2 = 0 then
      write('Parzysty ')
   else
      write('Nieparzysty ');
   writeln('element: ', i);
end;

Alternatywna wersja z zapisem w nowej linijce i zakazem stosowania zapisu bezklamrowego:

for i := 1 to 10 do
begin
   if i mod 2 = 0 then
   begin
      write('Parzysty ');
   end
   else
   begin
      write('Nieparzysty ');
   end;
   writeln('element: ', i);
end;

Paragrafy

Paragrafy stosuje się w celu grupowania powiązanych ze sobą instrukcji i wydzielenia takich zestawów z ciągu dłuższego kodu. Umożliwia to łatwą identyfikację poszczególnych kroków algorytmu. Paragrafy tworzy się, umieszczając pustą linię (lub kilka linii) pomiędzy kolejnymi blokami. Przykładowo w poniższym kodzie C++ funkcja została podzielona na cztery paragrafy: deklarację zmiennych, łączenie list do momentu napotkania końca jednej z nich, dodanie pozostałych elementów z dłuższej listy oraz zwrócenie wartości.

vector<int> merge(const vector<int>& left, const vector<int>& right) {
    vector<int> result;
    unsigned left_it = 0, right_it = 0;

    // Łączenie list do napotkania końca jednej z nich
    while(left_it < left.size() && right_it < right.size()) {
        if(left[left_it] < right[right_it]) {
            result.push_back(left[left_it]);
            left_it++;
        } else {
            result.push_back(right[right_it]);
            right_it++;
        }
    }

    // Dodanie reszty elementów z dłuższej listy
    while(left_it < left.size()) {
        result.push_back(left[left_it]);
        left_it++;
    }
    while(right_it < right.size()) {
        result.push_back(right[right_it]);
        right_it++;
    }

    return result;
}

Stosowanie paragrafów może zostać zastąpione przez wywołanie dodatkowych funkcji.

Długość linii

Ponieważ szerokość monitora jest ograniczona, tylko pewna liczba znaków w linii może być jednocześnie widoczna dla programisty. Dlatego stosuje się ograniczenie długości linii kodu. Popularne limity liczby znaków w linii to 80, 78 lub 120.

Nazewnictwo funkcji i zmiennych

Każda zmienna oraz funkcja w programie musi posiadać swoją nazwę, która będzie później wykorzystywana przez programistę we wszystkich odwołaniach do niej. Z tego powodu standardy kodowania poświęcają dużo miejsca ujednoliceniu zasad nazewnictwa. Rozpatrywane są zarówno kwestie wyglądu, jak i sensowności poszczególnych nazw. Dominującymi stylami zapisu są:

• podkreślenia (snake case): to_jest_nazwa,
• camelCase: toJestNazwa,
• PascalCase: ToJestNazwa,
• wielkie litery: TO_JEST_NAZWA.

Pojedynczy standard może wykorzystywać kilka stylów do oznaczania różnych elementów. Przykładowo, Java stosuje camelCase do nazewnictwa zmiennych i metod, upper camelCase do nazewnictwa klas i interfejsów oraz wielkie litery do stałych.

Pod względem semantycznym reguły uznają przeważnie za niepoprawny kod, w którym nazwy zmiennych i funkcji nie mówią nic o tym, do czego one służą (np. a, b, c). Nazwy powinny być krótkie, lecz znaczące, np. objectWidth.

Choć język na ogół nie jest określany przez standardy kodowania, niepisaną regułą jest wykorzystanie angielskiego zamiast języków narodowych.

Komentarze

Każdy praktycznie stosowany język programowania zezwala na tworzenie komentarzy, czyli fragmentów tekstu, które są pomijane przez interpreter bądź kompilator. W komentarzach programista może zapisać słownie dodatkowe informacje na temat działania czy zastosowania określonego kawałka kodu. Komentarze są powszechnie wykorzystywane przez narzędzia do automatycznego generowania dokumentacji na podstawie kodu źródłowego. Analizują one komentarze umieszczone nad funkcjami, zmiennymi i klasami, wyciągając z nich opis działania oraz dodatkowe znaczniki zawierające np. opisy argumentów.

Komentarze wykorzystuje się również do umieszczenia na początku każdego pliku informacji o prawach autorskich oraz licencji, którą objęty jest dany kod.

Zobacz też

• kod źródłowy
• metryka oprogramowania

Linki zewnętrzne

Standardy kodowania dla języków programowania

• ActionScript: Flex SDK coding conventions and best practices
• Ada: Ada 95 Quality and Style Guide: Guidelines for Professional Programmers
• Ada: Guide for the use of the Ada programming language in high integrity systems (ISO/IEC TR 15942:2000)
• Ada: NASA Flight Software Branch — Ada Coding Standard
• Ada: European Space Agency's Ada Coding Standard (BSSC(98)3)
• C: Ganssle Group's Firmware Development Standard
• C: Netrino Embedded C Coding Standard
• C: Micrium C Coding Standard
• C++: Quantum Leaps C/C++ Coding Standard
• C++: C++ Programming/Code Style
• C++: GeoSoft's C++ Programming Style Guidelines
• C++: Google's C++ Style Guide
• C#: Design Guidelines for Developing Class Libraries
• C#: Microsoft, Philips Healthcare
• D: The D Style
• Erlang: Erlang Programming Rules and Conventions
• Flex: Code conventions for the Flex SDK
• Java: Ambysoft's Coding Standards for Java
• Java: Code Conventions for the Java Programming Language
• Java: GeoSoft's Java Programming Style Guidelines
• Lisp: Riastradh's Lisp Style Rules
• Mono: Programming style for Mono
• Object Pascal: Object Pascal Style Guide
• Perl: Perl Style Guide
• PHP: PHP Framework Interop Group (PSR-0, PSR-1, PSR-2, PSR-3, PSR-4)
• PHP::PEAR: PHP::PEAR Coding Standards
• Python: Style Guide for Python Code
• Ruby: The Unofficial Ruby Usage Guide
• Ruby: Good API Design

Standardy kodowania dla projektów

• Apache Developers' C Language Style Guide
• Drupal PHP Coding Standards
• GNU Coding Standards
• Linux Kernel Coding Style
• ModuLiq Zero Indent Coding Style. moduliq.org. [zarchiwizowane z tego adresu (2011-01-27)].
• Mozilla Coding Style Guide
• Road Intranet's C++ Guidelines
• The NetBSD source code style guide (znane wcześniej jako BSD Kernel Normal Form)