Inżynieria Oprogramowania Standardy kodowania i dokumentowanie kodu (Na przykładzie języka Java i dokumentacji Javadoc) Cel zajęć Celem zajęć jest zapoznanie studentów z podstawowymi zasadami formatowania i dokumentowania kodu. Oba zagadnienia przedstawione zostaną na podstawie języka Java i narzędzia do tworze - nia dokumentacji Javadoc. Część I. Standardy kodowania Przedstawione wskazówki dotyczące formatowania kodu, są połączeniem ogólnie przyjętych dobrych praktyk i standardu kodowania dla języka Java: Sun Microsystems: Java Code Conventions, Mountain View, California 1997 http://java.sun.com/docs/codeconv/codeconventions.pdf 1. Nazwy plików Wszystkie nazwy powinny być unikalne, nie powinno się używać znaków specjalnych takich jak np. '#', '~', '\t', or '\n', oraz znaków narodowych. Pliki nie powinny nosić nazw zarezerwowanych dla urządzeń I/O lub portów: lpt1, com4, irq8. 2. Struktura pliku źródłowego Każdy plik źródłowy w Javie (.java), powinien zawierać pojedynczą klasę publiczną albo interfejs. Powiązane klasy prywatne mogą być umieszczone w tym samym pliku źródłowym, jednak ich nagłówek powinien wystąpić dopiero po klasie publicznej, czy interfejsie. Sekcje pliku źródłowego: Nazwa pakietu Sekcja importów Klasa publiczna albo interfejs o Nagłówek klasy/interfejsu -> nazwa z dużej litery, później na przemian - MojaKlasa o Pola statyczne klasy całość wielkimi literami z _ - MOJA_STALA o Pola klasy (każde pole w nowej linii) pierwszy znak z małej litery, później na przemian - mojepole Publiczne Chronione Prywatne o Konstruktory nazwa klasy o Metody (według funkcjonalności jaką udostępniają) tak jak pola mojametoda
3. Formatowanie kodu Dobre praktyki dotyczące formatowania kodu Wcięcie linii na 4 spacje (Tabulacje vs Spacje), Długość linii nie większa niż 80 znaków, Operatory i średniki oddzielaj spacjami, Jedno polecenia - jedna linia, Zawijanie linii jeśli wyrażenie nie mieści się w pojedynczej linii: o Złam linię po przecinku, o Złam linie przed operatorem, o Dokonuj wcięcia na głębokość taką samą jak kod w linii nadrzędnej tego samego poziomu Przykłady: Łamanie wierszy podczas wywołania metody: function(longexpression1, longexpression2, longexpression3, longexpression4, longexpression5); var = function1(longexpression1, function2(longexpression2, longexpression3)); Łamanie wierszy w przypadku wyrażeń arytmetycznych. Staraj się łamać wiersze pozostając na tym samym zagnieżdżeniu wyrażeń: + poprawnie longname1 = longname2 * (longname3 + longname4 - longname5) + 4 * longname6; - unikaj longname1 = longname2 * (longname3 + longname4 - longname5) + 4 * longname6; Łamanie wierszy w nagłówkach metod: Kolejne wiersze zagłębiamy, aż do otwierającego nawiasu parametrów somemethod(int anarg, Object anotherarg, String yetanotherarg, Object andstillanother) {... Kolejne wiersze parametrów zagłębiamy 8 spacjami: private static synchronized horkinglongmethodname(int anarg, Object anotherarg, String yetanotherarg, Object andstillanother) {... Zawijanie wierszy w wyrażeniach warunkowych. Staraj się używać 8 spacji, tak aby odróżnić wyrażenie warunkowe od kodu (ten wcinany jest przy użyciu 4 spacji) if ((condition1 && condition2) (condition3 && condition4)!(condition5 && condition6)) { dosomethingaboutit();
4. Formatowanie kodu w IDE - Eclipse Eclipse, jako środowisko do wytwarzania oprogramowania wspiera automatyczne formatowanie kodu. Aby, sformatować kod wybierz z menu Source->Format [Ctrl+Shift+F] przy aktywnym edytorze z kodem źródłowym. Możesz spróbować na kodzie w pakiecie pl.put.io.code.format. Istnieje możliwość konfiguracji auto-formatowania kodu, tak by spełniało nasze oczekiwania. Opcje formatowania znajdują się w Window->Preferences->Java->Code Style. Formatter Umożliwia konfigurację automatycznego formatowania kodu. Ćwiczenie: 1. Dodaj nowy profil IO (New ) bazujący na Eclipse [built-in] 2. Zmień sposób formatowania {, tak otwierający nawias był umieszczany w następnej linii po wyrażeniu. if (true) { 3. Zmień sposób formatowania wyrażeń if else, tak by po nawiasie otwierającym sekcje warunku dołożona została spacja. if ( true) { 4. Dodaj 4 linie pomiędzy nagłówkiem klasy, a pierwszą deklaracją. 5. Wzorce kodu Eclipse posiada możliwość tworzenia wzorców kodu (nie tylko dla edytora Javy). Wzorce kodu pozwalają zwiększyć efektywność programisty, dodatkowo zapewniają standard kodu (o ile są dobrze przygotowane). Wzorce dla edytora Javy można znaleźć w ustawieniach Java->Editor->Templates.
Wzorzec może posiadać dowolny kod. Można wykorzystywać predefiniowane zmienne, pod które podstawione są dostępne w kontekście wartości. Dla przykładu przeanalizujmy wzorzec dla pętli for iterującej po tablicy: for (int ${index = 0; ${index < ${array.length; ${index++) { ${line_selection${cursor Zmienne wyróżniane są poprzez znak ${zmienna. Istnieją predefiniowane zmienne, ale możemy dodawać nowe. W przykładzie powyżej zmienna ${index będzie wykorzystana jako licznik w pętli. Dodatkowo użyto predefiniowanej zmiennej ${array, która określa typ tablicowy poszukiwany w kontekście użycia. Wewnątrz bloku znajduje się wyrażenie ${line_selection${cursor, które zaznacza linię i dodaje miejsce w którym znajdzie się kursor (jeśli wywołamy wzorzec w kodzie za pomocą klawisza [TAB] możemy poruszać się po polach zmiennych (także polach ${cursor). Ćwiczenie: 1. Dodaj nowy wzorzec load_text_file. 2. Wzorzec ten powinien udostępniać fragment kodu umożliwiający operowanie linia po linii na pliku tekstowym. 3. Wykorzystaj klasy BufferedReader, FileReader. 4. Jako parametr dla konstruktora klasy FileReader powinien być wykorzystany obiekt klasy java.io.file, który poszukiwany będzie jako pole w klasie lub zmienna lokalna. Część II. Dokumentowanie kodu Dokumentacja kodu opiera się na dwóch filarach. Podstawą dokumentacji są komentarze umieszczone w kodzie. Z drugiej strony czytelny kod jest samo-komentujący się. Niestety, jeśli kod, który piszesz jest niezrozumiały i źle sformatowany, to żaden komentarz nie pomoże drugiej osobie zrozumieć twoich intencji. Wyróżniamy dwa typy komentarzy: Pierwszy nazywany jest implementacyjnym. Pozostaje on tylko w kodzie i ułatwia jego czytanie. W tym przypadku używamy komentarzy: // jednoliniowych, /* */ blokowych.
Drugi typ komentarzy nazywa się dokumentacyjnym. Oprócz polepszenia czytelności kodu ma on dodatkową zaletę, w postaci możliwości automatycznego wygenerowania dokumentacji w różnych formatach prosto z kodu. Komentarz taki umieszcza się w blokach /** */. Ten typ komentarzy jest przede wszystkim pożądany w przypadku pól i metod publicznych. Kompletny podręczniki Javadoc można znaleźć na stronie: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html 1. Tagi Javadoc Zanim przystąpimy do opisu komentarzy w konkretnych miejscach plików źródłowych zapoznaj się ze składnią i przeznaczeniem tagów wykorzystywanymi w komentarzach Javadoc. @author Jan Kowalski autor danego artefaktu, @version wersja artefaktu, @since wersja aplikacji, w której podany artefakt został dodany do API, @deprecated użycie danego artefaktu nie jest zalecane, ponieważ został on już zastąpiony przez inny. Należy podać link do artefaktu, który powinien być użyty w zamian (@link), @see NazwaKlasy, @see NazwaKlasy#nazwaMetody(), @see #nazwametodywtejklasie(), @see #nazwapolawtejklasie itd. referencje do klas, interfejsów, metod, które są powiązane z opisywanym artefaktem, {@link NazwaKlasy, {@link NazwaKlasy#nazwaMetody(), {@link #metodawtejklasie(), {@link #nazwapolawtejklasie itd. podobnie jak @see, ale umożliwia tworzenie odnośników do klasy, interfejsu, metody, pola wewnątrz akapitu, @param mojparametr opis parametru metody, @return opis zwracanej wartości, @throws KlasaWyjatku opis sytuacji. 2. Formatowanie komentarzy Javadoc Podstawowe zasady tworzenia komentarzy Javadoc Staraj się nie używać nazw pochodzących z API, jeśli nie są to odnośniki do artefaktów (lepiej jest parafrazować zachowanie), Komentuj w trzeciej osobie, Używaj tagów <p> </p> do wyodrębnienia akapitów, Używaj tagów <code> </code> do fragmentów kodu w komentarzu. 3. Nagłówek pliku źródłowego Plik źródłowy powinien rozpoczynać się komentarzem zawierającym nazwę klasy oraz notę copyright. 4. Komentarz klasy / interfejsu Nad deklaracją klasy/interfejsu umieszczamy komentarz opisujący jej przeznaczenie. Dodatkowo stosuje się tagi: @author, @version, @see. 5. Komentarz do pola Każde publiczne, chronione pole powinno posiadać komentarz, który wyjaśnia do czego stosowane jest pole i jakie posiada ograniczenia. 6. Komentarz do metody Każda metoda publiczna, chroniona powinna posiadać komentarz opisujący jej przeznaczenie, jak również zestaw przyjmowanych parametrów (@param), wartość zwracaną (@return), czy rzuca wyjątkiem (@throws) i czy jest niezalecana (@deprecated).
7. Opis pakietu Każdy pakiet może zawierać plik package.html, który opisuje przeznaczenie pakietu. Jako opis zostanie wykorzystany cała jego zawartość pomiędzy tagami <body></body>. Można stosować tagi Javadoc. 8. Javadoc i Eclipse W środowisku Eclipse możemy bardzo szybko i wygodnie dodawać komentarze do danej jednostki kodu, wybierając opcję Source->Generate Element Comment [Alt+Shift+J]. Przy pomocy środowiska Eclipse bardzo łatwo wygenerować dokumentację w postaci stron HTML, przy użyciu narzędzia Javadoc. Z menu Project wybieramy opcję Generate Javadoc. Warto również pamiętać o możliwości podania parametrów do wywołania komendy javadoc na ostatniej stronie kreatora (przydatny może się okazać parametr -charset Kodowanie i -encoding Kodowanie, np. -charset UTF-8 -encoding UTF-8). Ćwiczenie: Wygeneruj dokumentacje dla pakietu pl.put.io.document (zwróć uwagę, że w klasie jest referencja do klasy java.lang.math. Sformatuj kod i dodaj komentarze do projektu NamesActivitiesPlaces oraz wygeneruj dokumentację Javadoc.