środa, 11 czerwca 2008

Czytelność kodu i styl kodowania

Każdemu programiście zdarzyło się czytać cudzy kod. W ten sposób najszybciej można poznać dany język, nauczyć się trików. Czytanie takie sprawia przyjemność o ile kod jest czytelny.

Co to jest czytelność kodu? Każdy ma własną definicje, inaczej rozumie to słowo. Tak naprawdę trudno zdefiniować co to jest czytelność. Można powiedzieć, że kod jest czytelny gdy po przeczytaniu go raz od razu wiesz o co chodzi, skąd się biorą takie a nie inne wyniki i dlaczego akurat wybrano taką strukturę danych.
Jest kilka zasad tworzenia czytelnego kodu, podstawą jest tzw. styl kodowania (ang. coding styles) czyli ogólne zasady jak ma wyglądać pisany kod. Wielkość wcięć, gdzie łamać linie, kiedy wstawiać klamerki jak komentować, to podstawowe zagadnienia jakie powinny być omówione podczas tworzenia "Stylu kodowania".


Można by pomyśleć, że taki styl jest niepotrzebny, nie przyśpiesza przecież programu, a tylko wydłuża jego tworzenie, bo w końcu trzeba dodatkowo kod formatować. Nic bardziej mylnego, jeśli programujesz w grupie, styl kodowania potrafi znacząco przyśpieszyć pisanie programów. Gdy nad jednym projektem siedzi kilku programistów, często uzupełniają kod kolegów, jeśli jest on formatowany według ogólnych zasad w firmie/projekcie każdy programista bez problemu odczyta kolegi kod, co więcej, będzie się czuł jak we własnych bazgrołach i niemal od razu zacznie prace. Gdy natomiast każdy pisze według własnych modłów, osoba przejmująca kod musi najpierw przejść katorgę jaką jest czytanie i zrozumienie kodu.

Na co zwrócić uwagę

Styl kodowania nie musi być od razu rozbudowaną na kilkanaście stron specyfikacją, na początek wystarczy, że będzie zawierać najważniejsze struktury wykorzystywane podczas programowania. Ważne jest by styl był określony ściśle, nie powinny występować w nim wybory (pisz tak albo tak), jeśli pozostawimy jakikolwiek wybór w naszych zasadach, jest praktycznie pewne, że każdy wybierze własną drogę, a styl będzie można wyrzucić.

Należy unikać niejednoznaczności, zapis w stylu:
"zmienne piszemy camelcase-m"
dużo mówi, ale nie mówi wszystkiego, możemy przecież zaczynać z dużej bądź z małej litery; od podkreślenia lub dwóch. O wiele lepszym zapisem będzie:
"Zmienne należy pisać camelcase-m gdzie pierwsza litera będzie literą małą"

Jeśli macie już swoje coding styles, szkoda by było, gdyby ich nie używać. Trzymanie się stylów może być na początku dość denerwujące, ale szybko można się przyzwyczaić. Jeśli ktoś się ich nie trzyma można nałożyć niewielką karę lub dać mu do zrozumienia, że są one wymagane. Style nie są dla wybranych, są dla wszystkich.

Kilka podstawowych styli kodowania
Poniżej prezentuję kilka zasad które złożyć można w podstawowy styl, są to oczywiście propozycje, można je dowolnie modyfikować, nie zgadzać się z nimi bądź przyjąć za prawdę ostateczną.

Zmienne i stałe:
"Zmienne należy pisać camelcase-m zaczynając od małej litery (np. nazwaZmiennej). Zmienne prywatne powinny zaczynać się od znaku podkreślenia po czym następuje domyślna nazwa rozpoczynająca się od małej litery (np. _zmiennaPrywatna)
Stałe należy pisać używając duży liter, oddzielając kolejne tokeny znakami podkreślenia (np. STALA_PI)"

Metody:
"Nazwa metody powinna zaczynać się od małej litery po czym kolejne tokeny nazwy należy zaczynać z dużej litery (np. nazwaNowejMetody(...)).
Metody statyczne należy pisać rozpoczynając od litery dużej (np. NazwaMetodyStatycznej(...)).
Metody prywatne rozpoczynamy od podkreślenia po którym następują kolejne tokeny nazwy, pierwszy token należy rozpocząć od małej litery (_metodaPrywatna(...))."

Łamanie kodu:
"Linijka kodu powinna mieć długość maksymalnie 80 znaków, po których powinno nastąpić jej złamanie. Złamana linia kodu powinna być przesunięta o jeden tabulator od początku lini wyżej"

Tabulacje:
"Należy używać jednego tabulatora na wcięcie. Tabulator powinien składać się z 4 spacji"

Klamry:
"Klamra powinna być w odstępie jednej spacji od kodu, po klamrze należy dodać znak nowej lini."

PodsumowanieStyle są nieocenione choć wydawać się można, że mało potrzebne. Warto poświęcić im troszke czasu, najlepiej w grupie. Na starcie wszyscy będą zaznajomieni co do nowych norm w pisaniu kodu, każdy będzie mógł dodać coś od siebie, zaargumentować wypowiedź kolegi co dodatkowo wzmocni grupę. Same style o ile będą używane sumiennie na pewno polepszą komfort pracy.

3 komentarze:

  1. d.evil / quaddevśroda, 18 czerwca, 2008

    Za dużo się w życiu nie nakodowałem, ale kilka rzeczy w grupie było - zgadzam się - najbardziej właśnie wtedy standardy pisania, nawet własne, potrafią ułatwić pracę (że już nie wspomnę o oszczędzonych nerwach;)

    OdpowiedzUsuń
  2. Masz słusznego ;---)

    Dodał bym tylko że jeśli już wprowadzamy jakieś konwencje, to warto by od razu utworzyć zbiór reguł i wpiąć je do naszego ulubionego IDE, by on sam dbał o te wszystkie spacje, odstępy, podkreślał źle nazwane zmienne itp..

    No a dla niepokornych w większych organizacjach myślałem o robocie na systemie kontroli wersji, który sprawdzał by kod i mógłby odpowiedni raport wysłać :)

    OdpowiedzUsuń
  3. Tomasz:
    Zgadzam się, dzięki wprowadzeniu Coding Styles do IDE nie musimy się martwić o poprawne formatowanie, jednak tak czy siak, w głowie zawsze powinna być świadomość jak poprawnie pisać. Nie zawsze przecież mamy dostęp do naszego programu.

    OdpowiedzUsuń