Kontrola jakości projektu metodą client i server side control

<right>Łukasz Lechert</right>


Kontrola jakości projektu metodą client i server side control


<justify>
Każdy projekt złożonego systemu informatycznego obarczony jest ryzykiem. Ryzyka te dotyczą aspektów związanych z zarządzania wiedzą oraz jej transferem. Można wyobrazić sobie sytuację w której tylko jeden z programistów od początku pracujący w projekcie posiada szczegółową wiedzę na temat działania kluczowych modułów systemu. Pewnego dnia zachęcony intratną propozycją pracy odchodzi do konkurencji. Niektórzy stwierdzą, że nic się nie stało - damy sobie radę. Przewidujący i doświadczeni programiści dostaną gęsiej skórki. Brak świadomości konieczności posiadania wiedzy dostępnej dla całego zespołu prowadzi zazwyczaj do powstawania antywzorców. Prowadząc projekt na bazie metodyk lekkich, staramy się produkować jak najmniej dokumentów (kod ponad dokumentacją). W większości przedsięwzięciach minimum jakie musiał obligatoryjnie zagwarantować programista to stworzenie dokumentacji kodu źródłowego, zgodnie z zasadami ustalonymi w projekcie. Nie zawsze jednak się o tym pamięta. Pospieszne, automatyczne generowanie dokumentacji na bazie kodu źródłowego w wielu wypadkach spełnia tylko funkcje wywiązania się z umownych ustaleń z kontrahentem. Dostarczenie „dokumentacji” tylko w formie wydruku zbioru wyprodukowanych pakietów i klas oraz relacji między nimi nie spełnia podstawowych funkcji jakie ona ma pełnić.
</justify>

Cechy i funkcje dokumentacji

<justify>Każdy z nas ma ustala cele zawodowe, prywatne, które stara się osiągnąć w założonej perspektywie czasowej. Założenia oraz cele charakteryzują się cechami, które te elementy powinny koniecznie posiadać. Każdy cel powinien zostać sformułowany według koncepcji smart. Pierwszą cechą jest prostota. Definiując cele interpretacja nie powinna powodować kłopotów w jego zrozumieniu. Sformułowanie musi być jednoznaczne i nie pozostawiające miejsca na luźną interpretację. Cele powinny być małe i nie posiadać większego stopnia skomplikowania. Drugą cechą jest mierzalność. Element należy sformułować w taki sposób, by można było liczbowo wyrazić stopień lub przynajmniej umożliwić jednoznaczną weryfikację jego realizacji. Każde zamierzenie oraz działania z założenia powinny być realistyczne i osiągalne. Cel zbyt ambitny lub utopijny podkopuje wiarę w jego osiągnięcie oraz osłabia motywację do jego realizacji. Ze względu szybkość współczesnego życia cele powinny być istotne. Róbmy tylko to, co jest istotne w projekcie, a zadania o mniejszym priorytecie lub nie ważne można przesunąć na dalszy plan. Idąc dalej oraz biorąc pod uwagę ograniczenie 3 P  (wymagań, budżetu i czasu), cel musi być określony w czasie. Podsumowując, powinien mieć dokładnie określony horyzont czasowy w jakim zamierzamy go osiągnąć. Bazując na opisywanych cechach, można dokonać próby zdefiniowania podstawowych cech, jakimi będzie się charakteryzować dokumentacja kodu źródłowego. Przytoczony przykład jest tylko propozycją i w miarę powstania potrzeby może być  rozwijany według uznania Czytelnika.</justify>

<left>
Cechy dokumentacji kodu źródłowego</left>


  • jednoznaczność i spójność (prostota – Kto jest odbiorcą?),

  • kompletność (mierzalność – Ile wytworzymy dokumentacji?),

  • poprawność (istotność – Jakie informację przekażemy?),

  • zdolność do modyfikacji (horyzont czasowy - Jak długo będziemy ją tworzyć i pielęgnować?).

<justify>Kto jest odbiorcą? Odpowiedź na to pytanie w wielu zespołach jest bardzo prosta. Tylko programiści. Kod źródłowy tworzą programiści dla programistów. Zatem dokumentacja będzie wykorzystywana tylko do rozwoju kodu. Ale czy na pewno są to informacje zarezerwowane tylko dla osób bezpośrednio zaangażowanych w tworzenie kodu? Patrzą szerzej, z dokumentacji kodu źródłowego mogą korzystać testerzy, architekci lub przedstawiciele zleceniodawcy, weryfikujący jej poprawność podczas odbioru produktu. Dokumentacja powinna być poprawna językowo, jednoznaczna, prosta i spójna. Ma umożliwić klientowi rozwój jego systemu nawet w sytuacji braku wsparcia ze strony pierwotnego zleceniobiorcy. Ile jej wytworzymy? Raczej jak najmniej. „Po co opisywać coś co widać w kodzie”. Rzeczywiście, analizując kod źródłowy, można pozyskać informacje jak działa dana metoda oraz jaki algorytm implementuje. Rodzi się pytanie. Po co analizować kod jak można przeczytać dwa lub trzy zdania, że metoda wykorzystuje algorytm Forda-Bellmana obliczający najkrótszą odległość od wybranego wierzchołka grafu do pozostałych? Jest to informacja bardziej „strawna” niż składnia języka programowania. Podczas opracowywania dokumentacji należy również zachować umiar. Dokumentowanie prostych „seterów” i „geterów” nie jest dobrym pomysłem oraz może jedynie pełnić funkcję rozrywkową i rozbawiać zespół. Jedną z najistotniejszych cech jest zdolność do modyfikacji. Po pierwsze warto zadbać, żeby dokumentację można było dalej pielęgnować. Żargon i niedokładność byłych kolegów z zespołu nie musi być powszechnie i zawsze rozumiany. Po drugie wskazane jest żeby trochę pomyśleć o przyszłości i odpowiedzieć sobie na pytanie. Jak będzie pracować się z systemem i rozwijać kod za kilka lat, jeżeli klient zleci jego modyfikację oraz nie będzie informacji jak działają rozwiązania i będą występować braki w dokumentacji kodu źródłowego? W najgorszym wypadku pozostaje debugger, poklepanie po ramieniu oraz zlecenie nowego zadania najbardziej doświadczonym kolegom. Analogicznie jak dokumentacja dla administratora systemu, końcowego użytkownika, dobra dokumentacja kodu źródłowego pełni określone funkcje w procesie produkcji oprogramowania.</justify>

<left>Funkcje dokumentacji</left>


  • informacyjna (pomaga szybko wejść w wybrany temat),

  • archiwalna (przechowuje informacje o ewolucji systemu),

  • standaryzująca (pozwala wypracować własne praktyki odnoszące się do kodu źródłowego).

<justify>Nie istnieją globalne standardy i niezmienne reguły tworzenia dokumentacji kodu źródłowego. Chcąc poprawić jakość softwaru można pokusić się o opracowanie ogólnych zaleceń dotyczących dokumentowania kodu przez programistów.
</justify>

Zalecenia

<justify>Narzędziem javadoc oraz komentarze zawierające dokumentację stosuje wielu programistów java. Istotnym celem jest stworzenie dla projektu wytycznych określających jej poprawne tworzenie na potrzeby firmy. Wyzwanie nie jest trywialne z uwagi na fakt potrzeby znalezienia punktu równowagi pomiędzy użytecznością, prostotą oraz kompletnością. Przyglądając się projektom realizowanym w języku java, niezbędne jest dokumentowanie klas, interfejsów oraz typów wyliczanych. Przytoczone elementy powinny zostać udokumentowane obligatoryjnie. Oprócz opisu odpowiedzialności klasy, dokumentacja powinna zawierać informacje o autorze, wersji, informacji o wersji systemu, kiedy klasa się pojawiła oraz wiązania do systemu zarządzania kodem źródłowym. W miarę potrzeby można zamieścić linki do innych fragmentów dokumentacji powiązanych z klasą. Przykład minimalnej dokumentacji dla klas zawiera  fragment z listingu 1.
</justify>

Listing 1. Dokumentacja dla klasy

/**
 * Opis odpowiedzialności klasy
 *
 * @author  Inicjały developera
 * @since 1.0
 * @see link
*/


<justify>Kolejnym elementem są metody klas. Dokumentowanie poszczególnych metod powinno być obowiązkowe. Jako wyjątek  można przyjąć pominięcie opisów prostych “geterów” i “seterów”. W przypadku tak prostych metod uzasadnione jest dokumentowanie “geterów” i “seterów” w przypadku jeśli dotyczą one atrybutów, których znaczenie nie jest intuicyjne. W takiej sytuacji eleganckim rozwiązaniem jest dodanie odnośnika do odpowiedniego atrybutu, gdzie znajduje się szerszy opis. Przykład zastosowania tagu @see prezentuje listing 2.
</justify>

Listing 2. Zastosowanie tagu @see

/**
 * @see Person#phoneNumber
 */
 
public String getPhoneNumber() {
    return phoneNumber;
}




<justify>
Dokumentacja dla pozostałych metod musi zawierać tagi @param, @return i @throws, jeśli generuje wyjątki. Szczególną uwagę oraz obowiązkową dokumentację wymagają metody, które realizują skomplikowane algorytmy oraz interpretacja ich działania nie jest prosta. W takich przypadkach wymagany jest dodatkowa definicja wzorów z których korzysta metoda. Przykład takiej metody prezentuje listing 3.
</justify>

Listing 3. Dokumentacja dla algorytmów

/**
 * Oblicza marze wedlug wzoru ...
 *
 * @param sp cena zakupu
 * @param cp cena sprzedazy
 * @param tax podatek 
 * 
 * @return marza
 */
public double getMargin(double cp, double sp, double tax) {
    double margin = 0.0;
 
    if (vkp != 0) {        
        double helper = cp / sp;
 
        // Margin = 1 - Cost price / Selling price * (1 + (tax / 100)) 
       margin = 1 - helper * (1 + (tax / 100.0));
    }
 
    // Calculation ...
 
    return margin;
}



<justify>W przypadku atrybutów wielokrotnie pomija się dołączanie dokumentacji w kodzie źródłowym. Atrybuty są elementami, które zazwyczaj opisują się same, jednak w przypadku specjalistycznych pojęć np. z zakresu rachunkowości lub finansów przedsiębiorstw warto opisać co oznaczają. Podobnie jak w przypadku “geterów” i “seterów”, zaleca się dodawanie linków do atrybutów realizujących relację pomiędzy obiektami. Przykładem jest listing 4. </justify>


Listing 4. Łączenie klas w dokumentacji

public class Exam {
 
    /**
     * Pytania dla egzaminu
     *
     * @see Questions
     */
    Questions questions;
 
    public Questions getQuestions() {
            return questions;
    }
}



<justify>Pomocnymi narzędziami mogą się również okazać znaczniki HTML, które można zamieszczać wewnątrz komentarzy. Umożliwiają one formatowanie tekstu, wprowadzanie akapitów, oznaczanie tekstu jako kod źródłowy lub pogrubianie ważnych elementów. Stosowanie tych udogodnień może podnieść jakość i czytelność dokumentacji. Gdy dokumentacja kodu źródłowego jest gotowa do wprowadzenia do repozytorium, można dodatkowo sprawdzić jej poprawność oraz zgodność z globalnymi wytycznymi projektowymi. Na rynku dostępne są narzędzia, wiele z nich to narzędzia darmowe – open source, które umożliwiają sprawne przeprowadzenie kontroli poprawności dokumentacji w kodzie źródłowym java.</justify>

Kontrola poprawności  dokumentacji po stronie klienta i serwera

<justify>Poprawność opisów interfejsów jest istotna w całym procesie produkcji, a szczególnie w fazach pielęgnacji systemu. Należy mieć świadomość, że nie wszystkie elementy dadzą się w 100% skontrolować  i naprawić. Takim elementem jest tekst opisujący np. klasy w projekcie, na który nie ma się w większym stopniu wpływu. Kontrolować dokumentację można po stronie klienta, czyli programisty. Istnieją wady tego rozwiązania. Jedną z nich jest dokładność oraz sumienność autora dokumentacji. W skrajnych przypadkach do procesu budowy aplikacji i generowania dokumentacji  mogą się przedostać fragmenty, których jakość jest bardzo niska. Proces kontroli można wspomóc testem kodu źródłowego po stronie serwera, czyli testem kodu zapamiętanego w repozytorium systemu kontroli wersji.
W sieci dostępnych jest wiele projektów, które umożliwiają kontrolę dokumentacji w kodzie źródłowym projektu java. Każdy programista może skorzystać z wtyczki dla środowiska IDE Eclipse. Projekt Eclipse-CS jest darmowym rozwiązaniem, oferowanym na licencji LGPL. Rozwiązanie integruje analizator kodu źródłowego Checkstyle z Eclipsem 3.4 oraz gwarantuje weryfikację i kontrolę dokumentacji po stronie klienta. Instalacja wtyczki odbywa się w sposób standardowy. Z poziomu menu Help wybierając funkcję Software Updates, w prosty sposób można zainstalować wtyczkę, służącą do kontroli dokumentacji kodu źródłowego java. Po instalacji należy wskazać projekt do kontroli oraz prawym klawiszem myszy wybrać funkcję Properties → Checkstyle, a następnie włączyć kontrolę za pomocą przełącznika Checkstyle active for this project. Projekt zostanie zbudowany ponownie, a w edytorze kodu źródłowego wskazane zostaną istniejące błędy w dokumentacji, które nie są zgodne ze standardowym szablonem Sun Checks ustawionym po instalacji. Wtyczka Eclipse-CS udostępnia również tworzenie własnych szablonów, dostosowanych do potrzeb danego projektu. Chcąc stworzyć własny szablon należy przejść do zakładki Local Check Configurations oraz następnie za pomocą przycisku New stworzyć nową konfigurację szablonu. Tak stworzony element należy dodatkowo skonfigurować, klikając przycisk Configure. Z listy dostępnych elementów należy  wybrać Javadoc Comments oraz następnie element Method Javadoc w przypadku wprowadzania reguł dla metod klas. Dobrym ćwiczeniem jest wymuszenie konieczności wprowadzania w komentarzach dokumentacji tagów @return, @param oraz @throws. W tym przypadku w oknie Edit module configuration pozostawiamy odznaczone opcje allowMissingJavaDoc, allowMissingParamTag, allowMissingThrowsTag oraz  allowMissingReturnTag. Posiadając tak zdefiniowaną konfigurację jeżeli programista np. zapomni opisać wartości zwracane przez metodę, Eclipse powiadomi go o tym fakcie wyświetlając lupę oraz załączając dodatkowo informację  o brakującym elemencie w dokumentacji. </justify>

<justify>Eclipse-CS bazuje na narzędziu Checkstyle. Narzędzie Checkstyle łatwo integruje się z Jakarta Ant, co stwarza możliwości opracowania mechanizmów kontroli dokumentacji i kodu źródłowego java po stronie serwera. Integracja pozwala kontrolować kod globalnie, na poziomie repozytorium zarządzania wersjami rozwijanego systemu oraz raportować znalezione usterki i błędy. Wymienione narzędzia można następnie zintegrować z frameworkiem CruiseControl, którego pierwotnym zastosowaniem jest integracja procesu budowania aplikacji. Framework jest dostępny dla systemu operacyjnego Linux. CruiseControl może zostać wcielony w rolę “kontrolera” poprawności opracowanej dokumentacji w poszczególnych wydaniach projektu. Proces integracji można podzielić na dwa etapy. Pierwszy dotyczy połączenia narzędzia Ant z Checkstyle. Drugi krok jest włączeniem wcześniej przygotowanego zadania Anta do interfejsu CruiseControl. Najprostszą metodą integracji Anta z Checkstyle jest zdefiniownie odpowiedniego zadania w pliku build.xml. Przykładowy listing 5 przedstawia tą czynność.</justify>

Listing 5. Przykładowe zadanie Anta wykorzystujące Checkstyle

<target name="checkstyle"
        description="kontrola kodu projektu">
 
  <checkstyle config="docs/sun_checks.xml"
              failureProperty="checkstyle.failure"
              failOnViolation="false">
    <formatter type="xml" tofile="checkstyle_report.xml"/>
    <fileset dir="src" includes="**/*.java"/>
  </checkstyle>
 
  <style in="checkstyle_report.xml" out="checkstyle_report.html" style="checkstyle.xsl"/>
</target>




<justify>Po zdefiniowaniu zadania checkstyle, oraz po odpowiednim skonfigurowaniu ścieżek do pakietów jar  można korzystać z funkcjonalności, która kontroluje kod źródłowy. Wywołując zadanie z poziomu linii komend można w dowolnym czasie sprawdzić jej poprawność. Drugim krokiem jest integracja zadania z narzędziem CruiseControl. System cyklicznie w ustalonym czasie sprawdza źródła systemu oraz udostępnia raportowanie ewentualnych błędów. Konfiguracja z antem odbywa się w pliku config.xml w tagu <ant />. Znacznik ten posiada wiele atrybutów, które określają ścieżkę wywołania skryptu Anta, lokalizację logów procesu oraz zadanie do wykonania. Przykładowy fragment pliku konfiguracyjnego config.xml przedstawia listing 6.</justify>


Listing 6. Przykład integracji Anta z frameworkiem CruiseControl

<schedule>
    <ant antscript="C:\Java\apache-ant-1.6.1\bin\ant.bat"
         antworkingdir="D:\workspace\MyProject"
         buildfile="MyProject-nightlybuild.xml"
         uselogger="true"
         usedebug="false"/>
<schedule>



<justify>Opis nie wyczerpuje wszystkich możliwości prezentowanych narzędzi. Można zaproponować Czytelnikom własne próby i eksperymenty z prezentowanymi projektami. Dociekliwych użytkowników odsyłam do bogatej dokumentacji, która szczegółowo opisuje funkcje frameworka CruiseControl.  Automatyzacja prac kontrolnych dokumentacji kodu źródłowego z pewnością wzbogaci warsztat pracy firmy programistycznej oraz poprawi jakość wydawanej dokumentacji. Zachęcam do dalszych eksperymentów.
</justify>

Podsumowanie

<justify>Podsumujmy zalety, wady i nakłady pracy, które wiążą się z wdrożeniem własnych rozwiązań kontroli poprawności dokumentacji metodą client server. Niewątpliwie zespół zainteresowany tematem będzie musiał poświęcić czas na przemyślenia i opracowanie optymalnego, globalnego rozwiązania, dostosowanego do własnych potrzeb. Dodatkowo jeśli w projekcie korzysta się z narzędzi weryfikujących kod źródłowy systemu, należy również uwzględnić dostosowanie reguł do opracowanych standardów. Proces raportowania i późniejszych korekt wymaga wskazania odpowiednich priorytetów do popełnionych błędów. Wprowadzenie wytycznych w jednej organizacji, może na początku ograniczać swobodę członków zespołów, rodzić przyzwyczajenia, które nie będą miały zastosowania w projektach innych firm. Od programistów wymagana jest konsekwencja w działaniu i samodyscyplina w celu utrwalenia proponowanego standardu. Niewątpliwą zaletą stosowania własnego rozwiązania w tym obszarze jest wzrost jakości opracowywanej dokumentacji, co implikuje łatwiejszą, późniejszą pielęgnację i rozbudowę systemów.</justify>

Linki

Javadoc - http://java.sun.com/j2se/javadoc/
Eclipse-CS - http://eclipse-cs.sourceforge.net/
Ckeckstyle - http://checkstyle.sourceforge.net/
Jakarta Ant - http://ant.apache.org/
CruiseControl - http://cruisecontrol.sourceforge.net/