Inżynieria Oprogramowania

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.