Orice aplicație software dispune de mai multe forme de documentație. Principalele forme sunt:
Pe parcursul dezvoltării aplicației se pot genera și alte forme de documentație: raportare, administrativă, de natură legală.
Persoanele care se ocupă de realizarea documentației tehnice a unei aplicații / a unui produs sunt numite technical writers. Documentația tehnică va cuprinde cerințele software, proiectarea sistemului și arhitectura sistemului. Documentația tehnică este utilă utilizatorului avansat sau administratorului sau unui membru al serviciului de mentenanță a aplicației. Scopul acestei documentații este de a oferi informații/detalii despre funcționarea internă a aplicației și despre legătura între componente.
Documentația de utilizator este, în general, descrisă în cadrul unui manual de utilizare a aplicației. Documentația este destinată oricărui tip de utilizator și este orientată pe a prezenta funcționalitățile aplicației și modul de folosire a acesteia fără a insista pe modul în care aceasta este proiectată. Exceptând formatele standard de manual de utilizare, formele online de ajutor (forumuri, liste de discutii), FAQ-uri, how-to-uri, tutoriale, pot fi, de asemenea considerate documentație de utilizator.
În general, documentația se realizează pe un set de șabloane (template-uri) predefinite. Totuși, o dată cu dezvoltarea Web-ului, un număr din ce în ce mai mare de articole de documentație se găsesc pe wiki-uri, pagini web specializate, blog-uri, în special cele destinate dezvoltatorilor. Forme de documentare precum MSDN Library, Java Documentation, GNU libc sunt accesibile online.
În proiectele software, un rol foarte important pentru reușita aplicației și buna înțelegere între membrii echipei este modul în care se documentează funcțiile, metodele, clasele și bibliotecile expuse. Pentru aplicații de tip bibliotecă software, este necesar ca utilizatorului acestora (un dezvoltator) să îi fie bine definite și documentate funcțiile și interfețele expuse.
Forme de documentare a codului, interfețelor includ pagini de manual, pagini web, tutoriale, documente LaTeX, references etc. În general, majoritatea formelor de documentare utilizate oferă o interfață web (MSDN library, pagini de manual, pagini info, reference libc, Java API, Python Standard Library, PHP) pentru a facilita accesul și citirea acestora.
O formă posibilă de documentare a codului, utilizată cu succes de Java API este generarea automată de documentație din surse folosind utilitarul Javadoc. Folosind un stil special de comentare a surselor, care nu afectează lizibilitatea codului, aplicațiile de generare automată a documentației obțin, în diverse formate, cel mai răspândit fiind HTML, informații despre utilizarea funcțiilor/claselor/metodelor expuse.
Javadoc este o aplicație produsă de Sun Microsystems care permite generarea de documentație automată pentru surse Java. O descriere amplă a tag-urilor care sunt folosite pentru obținerea documentației găsiți aici. În exemplul de mai jos este prezentat modul în care este folosit Javadoc pentru generarea documentației pentru acest fișier Java. Rezultatul obținut este prezentat aici.
razvan@valhalla:~school/2009-2010/mps/labs/lab-06$ javadoc -author -version MpsTest.java Loading source file MpsTest.java... Constructing Javadoc information... MpsTest.java:16: cannot find symbol symbol : class myException location: class MpsTest public MpsTest() throws myException ^ Standard Doclet version 1.6.0_16 [...]
Doxygen permite generarea automată a documentației într-o diversitate de formate pentru un număr mare de limbaje de programare.
Aici găsiți documentația generată pentru acest fișier Python folosind acest fișier de configurare.
Pentru obținerea documentației se urmează trei pași:
razvan@valhalla:~school/2009-2010/mps/labs/lab-06$ doxygen -g mps-doxy.conf Configuration file `mps-doxy.conf' created. Now edit the configuration file and enter doxygen mps-doxy.conf to generate the documentation for your project
INPUT
este folosită pentru a selecta fișierele/directoarele care se doresc parsaterazvan@valhalla:~school/2009-2010/mps/labs/lab-06$ doxygen mps-doxy.conf Notice: Output directory `out-doxy/' does not exist. I have created it for you. Searching for include files... Searching for example files... Searching for images... Searching for dot files... [...]
Domeniul ingineriei software are o dinamică deosebită. Fiecare limbaj de programare sau paradigmă înseamnă folosirea altui set de reguli și noțiuni. Cu toate acestea există un set de reguli de bază care trebuie urmărite pentru a asigura succesul unei aplicații. Aceste reguli au ca scop integrarea facilă a aplicației cu alte aplicații, folosirea de interfețe ușor de înțeles, adăugarea ușoară de noi caracteristici. Un set de caracteristici pe care trebuie să le îndeplinească o aplicație sau un modul sunt:
Caracteristicile de mai sus sunt descrise în cartea The Practice of Programming de Brian Kernighan și Rob Pike.
Aceste caracteristici sunt generice la nivelul oricărui limbaj de programare. Apariția limbajelor de nivel foarte înalt oferă un context prin care dezvoltatorul nu trebuie să se preocupe de modul de proiectare/dezvoltare a aplicației. Aceste limbaje sunt, însă, foarte specifice astfel încât pentru majoritatea limbajelor este nevoie ca dezvoltatorul să aibă cunoștințe și experiențe în folosirea tehnicilor de tip “best practice” în inginerie software.
Tehnicile de tip “best practices” și ”(design) patterns” se referă la mecanisme de proiectare și implementare a unei aplicații/modul pentru ca aceasta să respecte cât mai bine caracteristicile de claritate, generalitate, simplitate. În acest sens se definesc o serie de principii/mecanisme pe care dezvoltatorul/programatorul este recomandat să le urmeze.
Noțiunea de “design pattern” (șablon de proiectare) se referă în special la limbajele orientate obiect. Un design pattern este o formă de abstractizare a unei soluții la o problemă într-o formă generică pentru a permite utilizarea soluției în alte situații. Exemple de design patterns sunt:
La un nivel generic, există noțiune de “development methodology/philosophy” sau tehnici/patterns pentru dezvoltarea aplicațiilor cu un nivel de genericitate ridicat - folosite de un spectru larg de limbaje de programare, nu doar cele orientate obiect. Între acestea amintim:
Un set important de principii, menționate în The Practice of Programming se referă la proiectarea interfeței expuse de un modul. O interfață proiectată corespunzător va facilita integrarea altor module și scalarea facilă a aplicației.
În ingineria programării anti-patterns sunt metode de proiectare (organizațional, software etc.) care, deși par evidente și simple sunt de fapt greșite, mai complexe decât e necesar sau suboptime. O listă de anti-pattern-uri clasice se găsesc pe wikipedia. Câteva anti-pattern-uri frecvente printre programatorii mai puțin experimentați sunt:
void setVisible(boolean); // mutator boolean isVisible(); // accesor
Modelele/Metodologiile de dezvoltare sunt, în general, clasificate după secvențialitatea acțiunilor. Există, astfel, două clase mari de metodologii de dezvoltare: liniare și iterative. În cadrul celor liniare, fiecare etapă a proiectului se bazează pe etapa anterioară. În cazul modelelor iterative, se realizează o primă parte a etapelor de proiectare, implementare și testare urmând ca, ulterior, să se treacă la faza următoare.
Modelul Waterfall este reprezentantul clasic al metodologiilor liniare. Fazele unui proiect (cerințe, proiectare, implementare, verificare, validare) se succed. Deși oferă o organizare a etapelor ce compun activitățile unui proiect, modelul Waterfall este în general privit ca o opțiune nepotrivită în cadrul proiectelor software. Principalul său dezavantaj este rigiditatea. Majoritatea proiectelor software nu pot defini de la bun început contextul în care se va implementa aplicația. Schimbarea rapidă a condițiilor, constrângerilor, opțiunilor pe parcursul desfășurării activităților proiectului impune iterarea procesului de proiectare/implementare/testare. O extensie a modelului Waterfall este modelul V.
Prototiparea software presupune crearea de prototipuri, versiuni incomplete ale programului care va fi realizat. Aceste prototipuri vor fi analizate și evaluate. Unele prototipuri vor fi aruncate, altele vor fi modificate, iar altele pot asigura baza pentru implementarea efectivă a unui modul/componente. RAD (Rapid Application Development) este o metodologie de dezvoltare software care include dezvoltarea iterativă și crearea de prototipuri.
Modelul spirală presupune realizarea unor cicluri de proiectare și prototipizare. În fiecare ciclu se parcurg 4 faze: determinarea obiectivelor, evaluarea riscurilor, dezvoltarea și verificarea livrabilelor, planificarea pentru următoarea iterație. Modelul spirală este, în general, folosit de companiile mari și activitățile complexe.
Modelul de dezvoltare agilă (agile software development) se referă la un set de tehnici bazate pe dezvoltare iterativă, în care soluțiile și cerințele evoluează prin intermediul colaborării între membrii diverselor echipe. Metodele agile încurajează inspecțiile frecvente, munca în echipă, auto-organizarea, responsabilitatea. Agile Manifesto a menționat noile valori ale modelului:
Scrum este o metodă iterativă/incrementală pentru gestiunea unei aplicații complexe, folosită, în general, la un loc cu agile development. Scrum presupune o serie de întâlniri/sprint-uri colaborative precum: daily scrum, scrum of scrums, sprint planning meeting, sprint-ul efectiv, sprint review meeting.
Un codesprint sau hackathon sau codefest este o activitate în care un grup de dezvoltatori se întâlnesc și programează colaborativ. Un hackathon presupune prezența unui număr considerabil de programatori și desfășurarea de activități pe parcursul câtorva zile până la maxim o săptămână.
Cele două forme comune de interfață cu utilizatorul sunt interfața mod text (CLI - Command Line Interface) și interfața mod grafic (GUI - Graphical User Interface). O dată cu dezvoltarea Internet-ului, se poate considera o nouă formă de interfață de natură grafică, denumită WebUI - Web User Interface.
Evoluția și răspândirea sistemelor de calcul și a aplicațiilor au dus la o creștere accelerată a interfețelor grafice și web în ultimele două decenii. Preponderent aplicațiile vor oferi o interfață grafică, deși interfața în linia de comandă rămâne utilizată pentru automatizare și eficiență sau de persoane cu profil tehnic (dezvoltatori, administratori de rețea/sistem).
Nivelul de intuitivitate, ușurință în folosire și eficiență a celor trei tipuri de interfețe variază dar există un set de decizii de proiectare care trebuie avute în vedere în momentul utilizării unei anumite interfețe.
Regula importantă pe care trebuie să o respecte orice interfață, indiferent de tipul acesteia este “oferă-i utilizatorului ceea ce se așteaptă”. O interfață care va inversa rolurile butoanelor OK și Cancel va încurca utilizatorul.
O aplicația care oferă o interfață în linia de comandă, va avea, în funcție de natura aplicației, un număr mai mare sau mai mic de argumente. În general argumentele sunt:
ls -a
, ps -e
);lsof -p 1001
(opțiunea -p
este asociată cu un pid ce reprezintă PID-ul unui proces);-t
, -l
, -p
, -n
);--tcp
, --listening
, --program
, --numeric
).
Argumentele trebuie să aibă nume intuitive și să permită folosirea tuturor opțiunilor importante ale aplicației. Opțiunile trebuie documentate și se recomandă o formă de ajutor rapid în acest sens (/?
pe Windows sau --help
pe Unix).
Pentru parsarea argumentelor se recomandă folosirea bibliotecii getopt, disponibilă și pentru Python, shell, Perl, PHP, Ruby.
O interfață grafică (GUI) folosește elemente descrise de WIMP: window, icon, menu, pointing device. Interfața grafică permite folosirea obiectelor anteriore pentru a obține un rezultat sau efect.
Interfața grafică are ca principal scop oferirea unei interfețe ușor de folosit și ergnomice. Paleta de culori folosită, fonturile, dimensiunea obiectelor și plasarea acestora sunt criterii importante pentru definirea interfeței grafice.
Aplicațiile grafice masive (de tipul desktop environment) dispun, în general, de un set de documente denumite human interface guidelines. Acestea oferă dezvoltatorilor și proiectanților un set de recomandări pentru a îmbunătăți experiența utilizatorilor. Aceste recomandări dictează regulile de utilizabilitate a aplicației. Exemple sunt:
Implementarea interfețelor grafice este facilitată de prezența toolkit-urilor grafice, denumite și widget toolkit, precum Microsoft Foundation Class pe Windows, GTK+ pentru aplicații GNOME, Qt pentru KDE, wxWidgets ca interfață portabilă între platforme.
Interfațele web (WebUI, WUI) sunt interfețele folosite în cadrul browserelor de paginile Web din Internet. O interfață web funcționează în contextul unui sistem client-server în care serverul este furnizorul paginii web care trebuie redată în client (browser). Pe lângă folosirea HTML ca mecanism de bază de reprezentare a paginii și comunicare client/server, noile aplicații dispun de tehnologii precum Ajax, Adobe Flex etc.
O interfață web trebuie să respecte, de asemenea, standarde de utilizabilitate. Totuși, o interfață web dispune de constrângeri suplimentare precum faptul că trebuie să funcționeze în contextul mai multor browsere și trebuie să țină cont de conexiunea/comunicarea client/server.
Evaluarea rezultatelor proiectului Pentru a evalua un proiect cel mai adesea se folosesc diverse metrici care să permită o analiză a rezultatelor obținute atât din punct de vedere cantitativ cât și calitativ.
Analiza cantitativă a rezultatelor presupune determinarea performanței soluției software dezvoltate în condiții ideale de rulare (ex: pentru o aplicație client-server se presupune că aplicația client comunică fără probleme cu server-ul, nu există delay etc.). Pentru o astfel de analiză ne interesează o acuratețe cât mai mare a rezultatelor oferite de un anumit algoritm, timpi cât mai buni de rulare etc. Este important ca pentru astfel de metrici să fie menționate condițiile în care a fost rulată aplicația (hardware, seturi de date etc.)
Analiza calitativă are mai mult o natură subiectivă și presupune evaluarea soluției propuse pe baza unor intrări și metrici care pun aplicația dezvoltată în anumite condiții limită. Aceste metrici au în vedere analiza robusteții aplicației și a algoritmilor dezvoltați în cadrul acesteia.
Unul dintre cele mai simple moduri de evidențiere a unor astfel de metrici este utilizarea de grafice, diagrame, tabele, etc. care permit persoanei care observă datele prezentate un mod rapid și eficient de analiză a acestora.
Pentru crearea de grafice există diverse instrumente care pot fi folosite pe lângă utilizarea arhicunoscutelor aplicații bazate pe spreadsheet-uri, precum Excel, pentru a crea diverse grafice simple. Unul dintre acestea este gnuplot care este un utilitar gratuit pentru linia de comandă ce poate fi rulat în cadrul a multiple sisteme de operare care a evoluat în timp pentru a oferi mai multe funcționalități. Unul dintre pachetele dezvoltate pe baza gnuplot este GNU Octave care este biblioteca folosită de către Matlab pentru realizarea de grafice. O altă bibliotecă utilă, gratuită, este matplotlib care este gândită mai mult pentru limbajul de dezvoltare python, dar care are diverse wrappere și pentru alte limbaje (ex: C++).
Indiferent de instrumentul utilizat în realizarea de grafice este important ca titlul, respectiv axele să fie etichetate în mod potrivit, cu nume sugestive, eventual pentru un graf cu mai multe variabile analizate să fie creată și o legendă care să specifice ce reprezintă fiecare variabilă.